CM.com Bank Transfer API

openapi: 3.2.0
info:
  title: Payments Gateway Bank Transfer API
  description: Common payments API
  version: 1.27.22
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: /api/v1
security:
- oAuth2ClientCredentials: []
tags:
- name: BankTransfer
  description: Bank Transfer payment method allows customers to pay by transferring funds directly from their bank account.
paths:
  /paymentmethods/banktransfer/v1/transactions:
    post:
      operationId: createBankTransferTransaction
      description: Create a new Bank Transfer payment transaction. The **id** field in the response can be used in future calls as **transactionId** to reference this transaction (for instance in a refund).
      tags:
      - BankTransfer
      summary: Create payment
      requestBody:
        description: Create Bank Transfer Transaction
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankTransferPayment'
      responses:
        '201':
          description: 'The Bank Transfer transaction was created successfully.


            The response contains the transaction details including bank account information for the consumer to complete the payment.'
          headers:
            Digest:
              $ref: '#/components/headers/Digest'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransferTransaction'
              examples:
                openBankTransfer:
                  $ref: '#/components/examples/openBankTransfer'
        4XX:
          $ref: '#/components/responses/UserError'
        5XX:
          $ref: '#/components/responses/InternalError'
  /paymentmethods/banktransfer/v1/transactions/{transactionId}:
    get:
      operationId: getBankTransferTransaction
      description: Retrieve details for an existing Bank Transfer transaction. This endpoint must be used to obtain the status for a transaction.
      tags:
      - BankTransfer
      summary: Fetch payment
      parameters:
      - $ref: '#/components/parameters/TransactionId'
      responses:
        '200':
          description: Returns the transaction details for the Bank Transfer transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransferTransaction'
              examples:
                openBankTransfer:
                  $ref: '#/components/examples/openBankTransfer'
                successBankTransfer:
                  $ref: '#/components/examples/successBankTransfer'
        4XX:
          $ref: '#/components/responses/UserError'
        5XX:
          $ref: '#/components/responses/InternalError'
  /paymentmethods/banktransfer/v1/transactions/{transactionId}/refunds:
    post:
      description: 'Create a refund for an existing Bank Transfer transaction. The **transactionId** parameter must be the ID of the transaction to be refunded.


        The **amount** field is required and must be a positive value, which is the amount to be refunded.'
      tags:
      - BankTransfer
      summary: Create refund
      operationId: createBankTransferRefund
      parameters:
      - $ref: '#/components/parameters/TransactionId'
      requestBody:
        description: Create Bank Transfer Refund
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Refund'
      responses:
        '201':
          description: The Bank Transfer refund was created successfully. The response contains the refund details.
          headers:
            Digest:
              $ref: '#/components/headers/Digest'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransferTransaction'
        4XX:
          $ref: '#/components/responses/UserError'
        5XX:
          $ref: '#/components/responses/InternalError'
    get:
      tags:
      - BankTransfer
      operationId: getBankTransferRefunds
      summary: Fetch refunds
      description: Retrieve refunds for an existing Bank Transfer transaction.
      parameters:
      - $ref: '#/components/parameters/TransactionId'
      responses:
        '200':
          $ref: '#/components/responses/RefundsResponse'
        4XX:
          $ref: '#/components/responses/UserError'
        5XX:
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    Language:
      description: Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).
      type: string
      default: nl
      example: nl
      minLength: 2
      maxLength: 2
    TransactionWithoutOrderIdLanguageRefundsAndExpiresAt:
      allOf:
      - $ref: '#/components/schemas/TransactionWithoutOrderIdLanguageRefundsCreatedAtAndExpiresAt'
      - type: object
        required:
        - createdAt
        properties:
          createdAt:
            $ref: '#/components/schemas/Datetime'
            description: ISO 8601 date and time when the transaction was created.
    TransactionWebhook:
      allOf:
      - $ref: '#/components/schemas/BaseWebhook'
      - type: object
        properties:
          events:
            items:
              description: '* `STATUS_CHANGE` - Triggered when the status of a transaction changes.

                * `REFUND_STATUS` - Triggered when a transaction receives an update on one of its requested refunds.

                * `FINALSTATUS` - This value is deprecated and shouldn''t be used anymore. Use `STATUS_CHANGE` instead.

                '
              oneOf:
              - $ref: '#/components/schemas/StatusChangeEvent'
              - $ref: '#/components/schemas/RefundStatusEvent'
              - $ref: '#/components/schemas/FinalStatusEvent'
              example: STATUS_CHANGE
    Gender:
      description: The consumers gender.
      type: string
      format: enum
      enum:
      - m
      - f
      - 'null'
      default: null
    Payment:
      allOf:
      - $ref: '#/components/schemas/PaymentWithoutDescriptionAndExpiresAt'
      - type: object
        required:
        - description
        properties:
          description:
            $ref: '#/components/schemas/Description'
          expiresAt:
            $ref: '#/components/schemas/Datetime'
            description: ISO 8601 date and time. If a transaction is not finalized before this time the status becomes **EXPIRED**.
    Refund:
      description: Refund an already successfully processed payment.
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
          description: 'Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

            '
        reason:
          $ref: '#/components/schemas/RefundReason'
    Amount:
      description: Denomination in the smallest currency subunit, as for example euro cents.
      type: integer
      minimum: 1
      maximum: 99999999
      example: 1200
    ReturnUrl:
      description: 'URL where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.


        With this implementation you are responsible to fetch the payment status and incorporated into your site.'
      type: string
      format: url
      maxLength: 2000
      example: https://yourdomain.tld/order/return?orderID=order123
    Reference:
      description: The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.
      type: string
      minLength: 1
      maxLength: 255
      example: '20210623130413'
    PaymentWithoutDescriptionExpiresAtLanguageAndWebhooks:
      allOf:
      - $ref: '#/components/schemas/ReturnURLOneOf'
      - type: object
        required:
        - reference
        - amount
        properties:
          reference:
            $ref: '#/components/schemas/Reference'
          amount:
            $ref: '#/components/schemas/Amount'
          currency:
            $ref: '#/components/schemas/Currency'
    RefundStatusEvent:
      description: '* `REFUND_STATUS` - Triggered when a transaction receives an update on one of its requested refunds.

        '
      type: string
      enum:
      - REFUND_STATUS
      example: REFUND_STATUS
    BankTransferTransaction:
      allOf:
      - $ref: '#/components/schemas/Transaction'
      - type: object
        required:
        - country
        - action
        - status
        properties:
          status:
            description: The status of the transaction.
            oneOf:
            - $ref: '#/components/schemas/StatusOpen'
            - $ref: '#/components/schemas/StatusSuccess'
            - $ref: '#/components/schemas/StatusCancelled'
            - $ref: '#/components/schemas/StatusExpired'
            - $ref: '#/components/schemas/StatusFailure'
            - $ref: '#/components/schemas/StatusAuthorized'
          country:
            $ref: '#/components/schemas/Country'
          action:
            anyOf:
            - type: object
              description: Next action to be performed by the merchant (or consumer) to complete the payment.
              properties:
                redirect:
                  $ref: '#/components/schemas/RedirectAction'
            - type: 'null'
    TransactionWithoutOrderId:
      allOf:
      - $ref: '#/components/schemas/TransactionWithoutOrderIdLanguageRefundsAndExpiresAt'
      - type: object
        required:
        - language
        - expiresAt
        properties:
          language:
            $ref: '#/components/schemas/Language'
          expiresAt:
            $ref: '#/components/schemas/Datetime'
            description: ISO 8601 date and time. If a transaction is not finalized before this time the status becomes **EXPIRED**.
          refunds:
            $ref: '#/components/schemas/Refunds'
    ReturnURLOneOf:
      oneOf:
      - type: object
        required:
        - returnUrls
        properties:
          returnUrls:
            $ref: '#/components/schemas/ReturnUrls'
      - type: object
        required:
        - returnUrl
        properties:
          returnUrl:
            $ref: '#/components/schemas/ReturnUrl'
    RedirectAction:
      description: URL where consumer should be redirected to by the merchant to perform the payment.
      type: object
      required:
      - url
      properties:
        url:
          description: URL where consumer should be redirected to by the merchant to perform the payment.
          type: string
          format: url
          example: https://issuer.tld/ideal/start?trxid=213981209381209390821&random=wreq0dq90vgq0ew923123
    Description:
      description: Description of the underlying value or reason of the payment.
      type: string
      maxLength: 255
      example: Order at yourdomain.tld
    Phone:
      description: The phonenumber of the consumer (E.164 format).
      type: string
      maxLength: 16
      example: '+31695613259'
    Country:
      description: Country of the consumer (ISO-3166)
      type: string
      example: NL
      minLength: 2
      maxLength: 2
    StatusOpen:
      description: The transaction is open and can be paid.
      type: string
      format: enum
      enum:
      - OPEN
      example: OPEN
    GenderlessConsumer:
      type: object
      properties:
        email:
          $ref: '#/components/schemas/Email'
        phone:
          $ref: '#/components/schemas/Phone'
        dateOfBirth:
          type: string
          format: date
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: '1990-05-23'
          description: Date of birth in ISO 8601 format (YYYY-MM-DD).
    StatusAuthorized:
      description: The transaction has been authorized.
      type: string
      format: enum
      enum:
      - AUTHORIZED
      example: AUTHORIZED
    StatusExpired:
      description: The transaction has expired.
      type: string
      format: enum
      enum:
      - EXPIRED
      example: EXPIRED
    PaymentWithoutDescriptionAndExpiresAt:
      allOf:
      - $ref: '#/components/schemas/PaymentWithoutDescriptionExpiresAtAndWebhooks'
      - type: object
        properties:
          webhooks:
            $ref: '#/components/schemas/TransactionWebhooks'
    BaseWebhook:
      type: object
      description: A single webhook object consists out of an URL to which we need to send the occurred event together with the event that needs to trigger the webhook call.
      required:
      - url
      - events
      properties:
        url:
          description: The URL the request must be send to.
          type: string
          format: url
          example: https://yourdomain.tld/webhooks?purchaseId=order123
        events:
          description: Type of events that will trigger a webhook.
          type: array
          minItems: 1
          items:
            type: string
    Transaction:
      allOf:
      - $ref: '#/components/schemas/TransactionWithoutOrderId'
      - type: object
        required:
        - orderId
        properties:
          orderId:
            allOf:
            - deprecated: true
            - $ref: '#/components/schemas/Uuid'
    TransactionWithoutOrderIdLanguageRefundsCreatedAtAndExpiresAt:
      allOf:
      - $ref: '#/components/schemas/ReturnURLOneOf'
      - type: object
        required:
        - id
        - reference
        - amount
        - currency
        - status
        - description
        properties:
          id:
            $ref: '#/components/schemas/TransactionId'
          reference:
            $ref: '#/components/schemas/Reference'
          amount:
            $ref: '#/components/schemas/Amount'
          currency:
            $ref: '#/components/schemas/Currency'
          webhooks:
            $ref: '#/components/schemas/TransactionWebhooks'
          description:
            $ref: '#/components/schemas/Description'
    RefundReason:
      description: 'The description for the refund for administrative purpose only. This reason will be visible in the portal.

        '
      type: string
      example: Refund required by consumer.
      maxLength: 255
    RefundsList:
      description: Details of all refunds belonging to a transaction.
      type: object
      required:
      - refunds
      properties:
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/RefundDetails'
    RefundStatus:
      description: '* `SUCCESS`    - Refund has succeeded.

        * `PENDING`    - Refund is waiting to be processed.

        * `FAILURE`    - Refund has failed.

        * `CANCELLED`  - Refund has been cancelled.

        '
      type: string
      enum:
      - SUCCESS
      - PENDING
      - FAILURE
      - CANCELLED
      example: SUCCESS
    Currency:
      description: ISO 4217 currency code.
      type: string
      minLength: 3
      maxLength: 3
      default: EUR
      example: EUR
    StatusSuccess:
      description: The transaction has been successfully paid.
      type: string
      format: enum
      enum:
      - SUCCESS
      example: SUCCESS
    Datetime:
      type: string
      format: date-time
      minLength: 20
      example: '2006-01-02T15:04:05Z'
      description: ISO 8601 date and time.
    StatusCancelled:
      description: The transaction has been cancelled by the consumer.
      type: string
      format: enum
      enum:
      - CANCELLED
      example: CANCELLED
    ReturnUrls:
      type: object
      description: 'URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.


        With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.'
      required:
      - success
      - cancelled
      - expired
      - failed
      properties:
        success:
          type: string
          format: url
          maxLength: 2000
          example: https://yourdomain.tld/order/payment-success.html
        cancelled:
          type: string
          format: url
          maxLength: 2000
          example: https://yourdomain.tld/order/payment-cancelled.html
        expired:
          type: string
          format: url
          maxLength: 2000
          example: https://yourdomain.tld/order/payment-expired.html
        failed:
          type: string
          format: url
          maxLength: 2000
          example: https://yourdomain.tld/order/payment-failed.html
    TransactionWebhooks:
      description: 'Array of webhooks that enables receiving a web request once a given event occurs. We won''t do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

        '
      type: array
      items:
        $ref: '#/components/schemas/TransactionWebhook'
      example:
      - url: https://yourdomain.tld/payment-webhooks?purchaseId=order123
        events:
        - STATUS_CHANGE
    TransactionId:
      description: ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.
      type: string
      format: uuid
      minLength: 36
      maxLength: 36
      example: 8db1e7fa-ba8a-4189-92fd-67a20217443d
    Refunds:
      description: Details of refunds for a transaction
      type: object
      required:
      - refundedAmount
      - refundedPendingAmount
      properties:
        refundedAmount:
          description: Amount in the smallest currency subunit, as for example euro cents, that has already been refunded.
          type: integer
          minimum: 0
          maximum: 99999999
          example: 300
        refundedPendingAmount:
          description: Amount in the smallest currency subunit, as for example euro cents, that has been requested to be refunded.
          type: integer
          minimum: 1
          maximum: 99999999
          example: 100
    StatusFailure:
      description: The transaction has failed.
      type: string
      format: enum
      enum:
      - FAILURE
      example: FAILURE
    Email:
      description: The email address of the consumer.
      type: string
      format: email
      example: john.doe@email.tld
    Consumer:
      allOf:
      - $ref: '#/components/schemas/GenderlessConsumer'
      - type: object
        properties:
          gender:
            $ref: '#/components/schemas/Gender'
    StatusChangeEvent:
      description: '* `STATUS_CHANGE` - Triggered when the status of a transaction changes.

        '
      type: string
      enum:
      - STATUS_CHANGE
      example: STATUS_CHANGE
    RefundDetails:
      description: Details of a refund.
      type: object
      required:
      - id
      - transactionId
      - amount
      - reason
      - status
      - created
      - updated
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        transactionId:
          $ref: '#/components/schemas/Uuid'
        amount:
          $ref: '#/components/schemas/Amount'
        reason:
          $ref: '#/components/schemas/RefundReason'
        status:
          $ref: '#/components/schemas/RefundStatus'
        created:
          $ref: '#/components/schemas/Datetime'
        updated:
          $ref: '#/components/schemas/Datetime'
    Uuid:
      description: Unique identifier
      type: string
      format: uuid
      minLength: 36
      maxLength: 36
      example: 8db1e7fa-ba8a-4189-92fd-67a20217443d
    PaymentWithoutDescriptionExpiresAtAndWebhooks:
      allOf:
      - $ref: '#/components/schemas/PaymentWithoutDescriptionExpiresAtLanguageAndWebhooks'
      - type: object
        properties:
          language:
            $ref: '#/components/schemas/Language'
    FinalStatusEvent:
      description: '* `FINALSTATUS` - This value is deprecated and shouldn''t be used anymore. Use `STATUS_CHANGE` instead.

        '
      type: string
      enum:
      - FINALSTATUS
      example: FINALSTATUS
    BankTransferPayment:
      allOf:
      - $ref: '#/components/schemas/Payment'
      - type: object
        required:
        - language
        - consumer
        properties:
          expiresAt:
            allOf:
            - $ref: '#/components/schemas/Datetime'
            - description: ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED. If left empty, the value defaults to 1 hour.
          consumer:
            $ref: '#/components/schemas/Consumer'
  responses:
    UserError:
      description: The user input was incorrect or something illegal was attempted (eg. using a service without having that service configured for the user, or not being authorized)
      content:
        application/json:
          schema:
            type: object
            required:
            - id
            - message
            properties:
              id:
                $ref: '#/components/schemas/Uuid'
              message:
                type: string
                example: no authorization methods provided
    InternalError:
      description: Internal server error. This can be caused by an unresponsive backend
      content:
        application/json:
          schema:
            type: object
            required:
            - id
            - message
            properties:
              id:
                $ref: '#/components/schemas/Uuid'
              message:
                type: string
                example: Service Unavailable
    RefundsResponse:
      description: Details of all refunds belonging to a transaction.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RefundsList'
  examples:
    openBankTransfer:
      summary: Open Bank Transfer transaction
      value:
        id: 1b4c8a2e-9d3f-4a7e-b5c1-6f8d2e3a9b7c
        orderId: 3e7f1a4b-2c8d-4b9e-a6f2-8d1c3b5e7a9f
        reference: '20210623130413'
        amount: 2500
        currency: EUR
        description: Order at yourdomain.tld
        expiresAt: '2025-06-02T15:04:05Z'
        language: nl
        country: NL
        webhooks:
        - url: https://yourdomain.tld/payment-webhooks?purchaseId=order123
          events:
          - STATUS_CHANGE
        status: OPEN
        action:
          redirect:
            url: https://checkout.gateway.cmpayments.nl/banktransfer/1b4c8a2e-9d3f-4a7e-b5c1-6f8d2e3a9b7c
        createdAt: '2025-05-27T13:03:04Z'
        returnUrl: https://yourdomain.tld/order/return?orderID=order123
    successBankTransfer:
      summary: Successful Bank Transfer transaction
      value:
        id: 1b4c8a2e-9d3f-4a7e-b5c1-6f8d2e3a9b7c
        orderId: 3e7f1a4b-2c8d-4b9e-a6f2-8d1c3b5e7a9f
        reference: '20210623130413'
        amount: 2500
        currency: EUR
        description: Order at yourdomain.tld
        expiresAt: '2025-06-02T15:04:05Z'
        language: nl
        country: NL
        webhooks:
        - url: https://yourdomain.tld/payment-webhooks?purchaseId=order123
          events:
          - STATUS_CHANGE
        status: SUCCESS
        action: null
        createdAt: '2025-05-28T11:53:32Z'
        returnUrl: https://yourdomain.tld/order/return?orderID=order123
  headers:
    Digest:
      description: Digest of the whole message body. Follow [RFC 3230](https://datatracker.ietf.org/doc/html/rfc3230) for more information.
      schema:
        type: string
        example: sha-256=OWM5MDc3ODYwNzdjYjE5NjU0Y2NjMDM4MzEyYzMxZTA5MTAzMDBjYWM1Y2I1ODM4NTdlMDU2MzhiMzE1ZDhjNw==
  parameters:
    TransactionId:
      name: transactionId
      description: ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/TransactionId'
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 Client Credentials Grant.
      flows:
        clientCredentials:
          tokenUrl: /api/v1/authorization/oauth2/token
          scopes: {}