Deutsche Bank Forms API

openapi: 3.2.0
info:
  title: Merchant-Server II REST Services Forms API
  version: v2.1
  description: The Forms API contains endpoints to initialize a form service interaction. It allows the merchant to redirect the customer to a customizable frontend page where the customer may enter sensitive payment data. After receipt of the necessary information, the frontend will carry out the transaction and redirect the customer back to the merchant’s page.
servers:
- url: https://testmerch.directpos.de/rest-api/services/v2.1/
security:
- bearerAuth: []
tags:
- name: Forms
  description: The Forms API contains endpoints to initialize a form service interaction. It allows the merchant to redirect the customer to a customizable frontend page where the customer may enter sensitive payment data. After receipt of the necessary information, the frontend will carry out the transaction and redirect the customer back to the merchant’s page.
paths:
  /form/alias/bankaccount:
    post:
      tags:
      - Forms
      summary: Creates a form to enter bank account data and create an alias for it
      operationId: formAliasBankAccountPost
      parameters:
      - name: Merchant-ID
        in: header
        description: Unique identification of the merchant for whom the transaction is carried out. This parameter is  required if the `Merchant-ID` cannot be derived from the `client_id` you used for authentication.
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 10
          minLength: 10
          pattern: '[0-9]+'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormRegisterAliasRequest'
            example:
              alias: AL1234_XY
              form_customer_continuation:
                success_url: https://www.example.com/target.php?success
                error_url: https://www.example.com/target.php?error
                notification_failed_url: https://www.example.com/target.php?notifyfailed
              callback:
                notify_url: http://www.example.com/notify
      responses:
        '400':
          description: Response in case of an error. Includes a response code and an error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Unauthorized request. Response body may be empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '200':
          description: Values required to initialize a form interaction. No transaction is created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormNoTxResponse'
  /form/alias/creditcard:
    post:
      tags:
      - Forms
      summary: Creates a form to enter credit card data and create an alias for it
      operationId: formAliasCreditCardPost
      parameters:
      - name: Merchant-ID
        in: header
        description: Unique identification of the merchant for whom the transaction is carried out. This parameter is  required if the `Merchant-ID` cannot be derived from the `client_id` you used for authentication.
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 10
          minLength: 10
          pattern: '[0-9]+'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormRegisterAliasRequest'
            example:
              alias: AL1234_XY
              form_customer_continuation:
                success_url: https://www.example.com/target.php?success
                error_url: https://www.example.com/target.php?error
                notification_failed_url: https://www.example.com/target.php?notifyfailed
              callback:
                notify_url: http://www.example.com/notify
      responses:
        '400':
          description: Response in case of an error. Includes a response code and an error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Unauthorized request. Response body may be empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '200':
          description: Values required to initialize a form interaction. No transaction is created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormNoTxResponse'
  /form/alias/klarna:
    post:
      tags:
      - Forms
      summary: Creates an authorization form for a Klarna payment alias
      operationId: formAliasKlarnaPost
      parameters:
      - name: Merchant-ID
        in: header
        description: Unique identification of the merchant for whom the transaction is carried out. This parameter is  required if the `Merchant-ID` cannot be derived from the `client_id` you used for authentication.
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 10
          minLength: 10
          pattern: '[0-9]+'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormRegisterAliasKlarnaRequest'
            example:
              alias: AL1234_XY
              form_customer_continuation:
                success_url: https://www.example.com/target.php?success
                error_url: https://www.example.com/target.php?error
                notification_failed_url: https://www.example.com/target.php?notifyfailed
              callback:
                notify_url: http://www.example.com/notify
              customer_information:
                date_of_birth: '1980-01-01'
              shipping_address:
                title: Ms
                first_name: Jane
                last_name: Doe
                email: test_jane@gmail.com
                address_line_1: Main Street 123
                address_line_2: Building A
                address_line_3: Apartment 12
                postal_code: '80469'
                phone_contact:
                  phone_type: MOBILE
                  phone_number: '+4917614287464'
                city: Munich
                country: DE
                extensions: {}
              billing_address:
                title: Ms
                first_name: Jane
                last_name: Doe
                email: test_jane@gmail.com
                address_line_1: Main Street 123
                address_line_2: Building A
                address_line_3: Apartment 12
                postal_code: '80469'
                phone_contact:
                  phone_type: MOBILE
                  phone_number: '+4917614287464'
                city: Munich
                country: DE
                extensions:
                  klarna_data:
                    custom_payment_method_ids: []
              basket:
                basket_id: basket123456
                invoice_id: RE123345
                soft_descriptor: 800-123-1234
                shipping_costs:
                  amount: 200
                  currency: EUR
                basket_type: DIGITAL
                extensions:
                  paypal_data:
                    custom_id: CUSTOMID123
                basket_items:
                - name: A fine shirt
                  description: BI123456
                  reference: UGG-BB-PUR-06
                  quantity:
                    quantity_amount: 5
                    quantity_unit: pcs
                  unit_price:
                    net: 100
                    gross: 100
                    currency: EUR
                    tax: 1900
                  discount:
                    net: 0
                    gross: 0
                    currency: EUR
                    tax: 1900
                  extensions:
                    klarna_data:
                      klarna_type: PHYSICAL
                      image_url: https://upload.wikimedia.org/wikipedia/commons/thumb/a/a5/Camisade_pu%C3%B1o_doble.jpg/256px-Camisade_pu%C3%B1o_doble.jpg
              amount_total:
                amount: 700
                currency: EUR
      responses:
        '400':
          description: Response in case of an error. Includes a response code and an error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Unauthorized request. Response body may be empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '200':
          description: Values required to initialize a form interaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormResponse'
  /form/event/{event_id}/checkout/{tx_action}:
    post:
      tags:
      - Forms
      summary: Creates a redirect to a checkout page where the customer may choose one of the…
      operationId: formCheckoutPost
      parameters:
      - name: Merchant-ID
        in: header
        description: Unique identification of the merchant for whom the transaction is carried out. This parameter is  required if the `Merchant-ID` cannot be derived from the `client_id` you used for authentication.
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 10
          minLength: 10
          pattern: '[0-9]+'
          type: string
      - name: event_id
        in: path
        description: A unique ID for the event.
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 50
          minLength: 1
          pattern: '[\/0-9a-zA-Z_.:,\-+*$%]+'
          type: string
      - name: tx_action
        in: path
        description: The action of an initial transaction.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - authorization
          - preauthorization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormCheckoutRequest'
            example:
              checkout_page_configuration:
                direct_debit_data:
                  mandate:
                    reference: MDT1620213727383XY
                    mandate_name: Sample mandate name
                    signed_on: '2020-12-30'
                    mandate_sequence_type: ONEOFF
                request_to_pay_data:
                  customer_id: testCustrID
                checkout_entry_sorting_order:
                - DIRECTDEBIT
                - REQUEST_TO_PAY
              amount_total:
                amount: 100
                currency: EUR
              form_customer_continuation:
                success_url: https://www.example.com/target.php?success
                error_url: https://www.example.com/target.php?error
                notification_failed_url: https://www.example.com/target.php?notifyfailed
              callback:
                notify_url: http://www.example.com/notify
      responses:
        '400':
          description: Response in case of an error. Includes a response code and an error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Unauthorized request. Response body may be empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '200':
          description: "Values required to initialize a form interaction, a return code and a message. In case of a known business or persistence error,\n                    only error code and message are provided."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormResponse'
  /form/event/{event_id}/creditcard/{tx_action}:
    post:
      tags:
      - Forms
      summary: Creates a form to enter credit card data and then proceed with the transaction…
      operationId: formCreditCardPost
      parameters:
      - name: Merchant-ID
        in: header
        description: Unique identification of the merchant for whom the transaction is carried out. This parameter is  required if the `Merchant-ID` cannot be derived from the `client_id` you used for authentication.
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 10
          minLength: 10
          pattern: '[0-9]+'
          type: string
      - name: event_id
        in: path
        description: A unique ID for the event.
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 50
          minLength: 1
          pattern: '[\/0-9a-zA-Z_.:,\-+*$%]+'
          type: string
      - name: tx_action
        in: path
        description: The action of an initial transaction.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - authorization
          - preauthorization
          - verify-mop
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormCreditCardRequest'
            examples:
              exampleccv2.1a:
                summary: Sample initialization of a credit card transaction.
                description: Redirect the customer to the URL received in the result.
                value:
                  amount_total:
                    amount: 100
                    currency: EUR
                  form_customer_continuation:
                    success_url: https://www.example.com/target.php?success
                    error_url: https://www.example.com/target.php?error
                    notification_failed_url: https://www.example.com/target.php?notifyfailed
                  callback:
                    notify_url: http://www.example.com/notify
                  billing_address:
                    first_name: Heinz
                    last_name: Müller
                    email: heinz@email.com
                    address_line_1: Rohrteichstr 18
                    address_line_2: EG R. 184
                    address_line_3: Wohnhaus
                    state: SN
                    postal_code: '04347'
                    city: Leipzig
                    country: DE
      responses:
        '400':
          description: Response in case of an error. Includes a response code and an error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Unauthorized request. Response body may be empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '200':
          description: "Values required to initialize a form interaction, a return code and a message. In case of a known business or persistence error,\n                    only error code and message are provided."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormResponse'
  /form/event/{event_id}/directdebit/{tx_action}:
    post:
      tags:
      - Forms
      summary: Creates a form to enter bank account data and then proceed with an SDD…
      operationId: formDirectDebitPost
      parameters:
      - name: Merchant-ID
        in: header
        description: Unique identification of the merchant for whom the transaction is carried out. This parameter is  required if the `Merchant-ID` cannot be derived from the `client_id` you used for authentication.
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 10
          minLength: 10
          pattern: '[0-9]+'
          type: string
      - name: event_id
        in: path
        description: A unique ID for the event.
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 50
          minLength: 1
          pattern: '[\/0-9a-zA-Z_.:,\-+*$%]+'
          type: string
      - name: tx_action
        in: path
        description: The action of an initial transaction.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - authorization
          - preauthorization
          - verify-mop
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormDirectDebitRequest'
            example:
              amount_total:
                amount: 100
                currency: EUR
              direct_debit_data:
                mandate:
                  reference: MDT1620213727383XY
                  mandate_name: Sample mandate name
                  signed_on: '2020-12-30'
                  mandate_sequence_type: ONEOFF
              form_customer_continuation:
                success_url: https://www.example.com/target.php?success
                error_url: https://www.example.com/target.php?error
                notification_failed_url: https://www.example.com/target.php?notifyfailed
              callback:
                notify_url: http://www.example.com/notify
      responses:
        '400':
          description: Response in case of an error. Includes a response code and an error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Unauthorized request. Response body may be empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '200':
          description: "Values required to initialize a form interaction, a return code and a message. \n                    In case of a known business or persistence error,\n                    only error code and message are provided."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormResponse'
  /form/event/{event_id}/giropay/{tx_action}:
    post:
      tags:
      - Forms
      summary: Initializes a giropay transaction (payment, avs, or avspayment)
      description: Start a new giropay transaction sequence. Customers should be redirected to the returned URL.
      operationId: formGiropayInitPost
      parameters:
      - name: Merchant-ID
        in: header
        description: Unique identification of the merchant for whom the transaction is carried out. This parameter is  required if the `Merchant-ID` cannot be derived from the `client_id` you used for authentication.
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 10
          minLength: 10
          pattern: '[0-9]+'
          type: string
      - name: event_id
        in: path
        description: A unique ID for the event.
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 50
          minLength: 1
          pattern: '[\/0-9a-zA-Z_.:,\-+*$%]+'
          type: string
      - name: tx_action
        in: path
        description: The action of an initial transaction.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - payment
          - avs
          - avspayment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormGiropayRequest'
            examples:
              sample21:
                summary: Sample giropay initialization request.
                description: Start a new giropay transaction sequence.
                value:
                  form_customer_continuation:
                    success_url: https://www.example.com/target.php?success
                    error_url: https://www.example.com/target.php?error
                    notification_failed_url: https://www.example.com/target.php?notifyfailed
                  callback:
                    notify_url: http://www.example.com/notify
                  amount_total:
                    amount: 100
                    currency: EUR
                  basket:
                    basket_id: basketId1639066152436
                    order_amount:
                      amount: 900
                      currency: EUR
                    shipping_costs:
                      amount: 100
                      currency: EUR
                    basket_type: PHYSICAL
                    basket_items:
                    - name: PhysicalBasketItem
                      description: A basket item
                      quantity:
                        quantity_amount: 1
                        quantity_unit: pcs
                      unit_price:
                        net: 756
                        gross: 900
                        currency: EUR
                        tax: 1900
      responses:
        '400':
          description: Response in case of an error. Includes a response code and an error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Unauthorized request. Response body may be empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '200':
          description: "A return code and a message, accompanied by an appropriate redirect URL. In case of a known business or persistence error,\n                    only error code and message are provided."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormResponse'
  /form/event/{event_id}/klarna/{tx_action}:
    post:
      tags:
      - Forms
      summary: Initializes a Klarna transaction (pre-authorization or authorization)
      description: Start a new Klarna transaction sequence. Customers should be redirected to the returned URL.
      operationId: formKlarnaInitPost
      parameters:
      - name: Merchant-ID
        in: header
        description: Unique identification of the merchant for whom the transaction is carried out. This parameter is  required if the `Merchant-ID` cannot be derived from the `client_id` you used for authentication.
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 10
          minLength: 10
          pattern: '[0-9]+'
          type: string
      - name: event_id
        in: path
        description: A unique ID for the event.
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 50
          minLength: 1
          pattern: '[\/0-9a-zA-Z_.:,\-+*$%]+'
          type: string
      - name: tx_action
        in: path
        description: The action of an initial transaction.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - authorization
          - preauthorization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormKlarnaRequest'
            example:
              shipping_address:
                title: Ms
                first_name: Jane
                last_name: Doe
                email: test_jane@gmail.com
                address_line_1: Main Street 123
                address_line_2: Building A
                address_line_3: Apartment 12
                postal_code: '80469'
                city: Munich
                state: BY
                country: DE
                extensions:
                  alternative_address_data:
                    street: Main Street
                    street_number: 123a
              billing_address:
                title: Ms
                first_name: Jane
                last_name: Doe
                email: test_jane@gmail.com
                address_line_1: Main Street 123
                address_line_2: Building A
                address_line_3: Apartment 12
                postal_code: '80469'
                city: Munich
                state: BY
                country: DE
              basket:
                basket_id: basket123456
                invoice_id: RE123345
                soft_descriptor: 800-123-1234
                shipping_costs:
                  amount: 200
                  currency: EUR
                basket_type: PHYSICAL
                basket_items:
                - name: A fine shirt
                  description: BI123456
                  reference: UGG-BB-PUR-06
                  quantity:
                    quantity_amount: 5
                    quantity_unit: pcs
                  unit_price:
                    net: 10000
                    gross: 11900
                    currency: EUR
                    tax: 1900
                  item_discount:
                    net: 0
                    gross: 0
                    currency: EUR
                    tax: 1900
                  extensions:
                    klarna_data:
                      image_url: https://upload.wikimedia.org/wikipedia/commons/thumb/a/a5/Camisade_pu%C3%B1o_doble.jpg/256px-Camisade_pu%C3%B1o_doble.jpg
              customer_information:
                customer_id: C1234-AX
                date_of_birth: '1975-06-30'
                gender: FEMALE
                title: Ms
                personal_identifications:
                - type: PASSPORT
                  id: T220001297
                  issued_by: DE
              form_data:
                locale: en
              form_customer_continuation:
                success_url: https://www.example.com/target.php?success
                error_url: https://www.example.com/target.php?error
                notification_failed_url: https://www.example.com/target.php?notifyfailed
              callback:
                notify_url: http://www.example.com/notify
              amount_total:
                amount: 59700
                currency: EUR
              merchant_information:
                merchant_data_1: merchantData1
                merchant_data_2: merchantData2
                merchant_data_3: merchantData3
      responses:
        '400':
          description: Response in case of an error. Includes a response code and an error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Unauthorized request. Response body may be empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '200':
          description: "A return code and a message, accompanied by an appropriate redirect URL. In case of a known business or persistence error,\n                    only error code and message are provided."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormResponse'
  /form/event/{event_id}/p24:
    post:
      tags:
      - Forms
      summary: Initializes a Request to P24 transaction (authorization)
      operationId: formP24Post
      parameters:
      - name: Merchant-ID
        in: header
        description: Unique identification of the merchant for whom the transaction is carried out. This parameter is  required if the `Merchant-ID` cannot be derived from the `client_id` you used for authentication.
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 10
          minLength: 10
          pattern: '[0-9]+'
          type: string
      - name: event_id
        in: path
        description: A unique ID for the event.
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 50
          minLength: 1
          pattern: '[\/0-9a-zA-Z_.:,\-+*$%]+'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormP24Request'
            example:
              form_customer_continuation:
                success_url: https://www.example.com/target.php?success
                error_url: https://www.example.com/target.php?error
                notification_failed_url: https://www.example.com/target.php?notifyfailed
              billing_address:
                first_name: Heinz
                last_name: Müller
                email: heinz@email.com
                address_line_1: Rohrteichstr 18
                address_line_2: EG R. 184
                address_line_3: Wohnhaus
                state: SN
                postal_code: '04347'
                city: Leipzig
                country: DE
              callback:
                notify_url: http://www.example.com/notify
              amount_total:
                amount: 100
                currency: EUR
      responses:
        '400':
          description: Response in case of an error. Includes a response code and an error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Unauthorized request. Response body may be empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '200':
          description: "Values required to initialize a form interaction, a return code and a message. In case of a known business or persistence error,\n                    only error code and message are provided."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormResponse'
  /form/event/{event_id}/psd2/authorization:
    post:
      tags:
      - Forms
      summary: Initializes a PSD2 payment transaction (authorization)
      operationId: formPSD2AuthorizationPost
      parameters:
      - name: Merchant-ID
        in: header
        description: Unique identification of the merchant for whom the transaction is carried out. This parameter is  required if the `Merchant-ID` cannot be derived from the `client_id` you used for authentication.
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 10
          minLength: 10
          pattern: '[0-9]+'
          type: string
      - name: event_id
        in: path
        description: A unique ID for the event.
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 50
          minLength: 1
          pattern: '[\/0-9a-zA-Z_.:,\-+*$%]+'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormPSD2AuthorizationRequest'
            example:
              amount_total:
                amount: 100
                currency: EUR
              callback:
                notify_url: http://www.example.com/notify
              form_customer_continuation:
                success_url: https://www.example.com/target.php?success
                error_url: https://www.example.com/target.php?error
                notification_failed_url: https://www.example.com/target.php?notifyfailed
              form_data:
                locale: fr
              psd2_pis_data:
                processing_options:
                - INSTANT_IF_POSSIBLE
      responses:
        '400':
          description: Response in case of an error. Includes a response code and an error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Unauthorized request. Response body may be empty.
          content:
   

# --- truncated at 32 KB (170 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/deutsche-bank/refs/heads/main/openapi/deutsche-bank-forms-api-openapi.yml