openapi: 3.1.1 info: title: IBAN Verification API description: | Use CM's IBAN Verification API to retrieve a person's International Bank Account Number (IBAN) using iDEAL | Wero. This requires a merchant token. If you have not yet received a merchant token, you can request one via [this link](https://www.cm.com/app/verification-registration/iban-verification/). version: "1" servers: - url: https://api.cm.com/ibancheck/v1.0 tags: - name: Transaction paths: /transaction: post: operationId: create_transaction tags: - Transaction summary: Create transaction description: | Start an IBAN Verification request requestBody: description: Start content: application/json: schema: $ref: '#/components/schemas/TransactionRequest' required: true responses: "200": description: Successful transaction content: application/json: schema: $ref: '#/components/schemas/TransactionResponse' default: description: Any non-compliant request will return an error object content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /status: post: operationId: get_status tags: - Transaction summary: Get transaction status description: | After the user has returned to you via your `merchant_return_url`, you retrieve the `transaction_id` from the trxid parameter. You should check that both the `entrance_code` and the `transaction_id` match your expectations for that consumer, before you make this status call. requestBody: content: application/json: schema: $ref: '#/components/schemas/StatusRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/StatusResponse' default: description: Any non-compliant request will return an error object content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: MerchantToken: type: string description: "a UUID string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 3c01abeb-b031-4fea-9f2d-c55c283cd78e" format: uuid examples: [ 3c01abeb-b031-4fea-9f2d-c55c283cd78e ] TokenizedRequest: title: TokenRequestParameters required: - merchant_token type: object properties: merchant_token: $ref: '#/components/schemas/MerchantToken' TransactionRequest: title: Transaction request allOf: - $ref: '#/components/schemas/TokenizedRequest' - required: - entrance_code - merchant_return_url type: object properties: entrance_code: maxLength: 40 minLength: 1 pattern: "^[a-zA-Z0-9]+$" type: string description: | This is a token that will allow you to rejoin the user to his session when he returns. It can be a maximum of 40 characters and should only contain the characters a-z, A-Z and 0-9. It should only be valid once and needs to be random enough (best use a cryptographically secure random generator), to avoid the possibility of replay attacks. merchant_return_url: maxLength: 512 type: string description: | The place where the bank should redirect the user to at the end of the flow. The bank will append two query parameters to this url when returning the user to you, `trxid` and `ec`. The latter will contain the value of entranceCode, trxid is the `transaction_id` that you will receive in this request. TransactionResponse: title: Transaction response required: - issuer_authentication_url - merchant_reference - transaction_id type: object properties: transaction_id: $ref: '#/components/schemas/TransactionID' issuer_authentication_url: maxLength: 512 type: string description: | The location where you should forward the customer to. They will begin their bank authentication here. examples: [ https://myserver/callback ] merchant_reference: maxLength: 35 pattern: "^[a-zA-Z0-9]+$" type: string description: An internal reference id for accounting purposes StatusRequest: title: StatusRequest allOf: - $ref: '#/components/schemas/TokenizedRequest' - title: StatusRequestParameters required: - merchant_reference - transaction_id type: object properties: transaction_id: $ref: '#/components/schemas/TransactionID' merchant_reference: maxLength: 35 pattern: "^[a-zA-Z0-9]+$" type: string description: The private reference of the transaction StatusResponse: title: The results of the information requested. type: object properties: transaction_id: $ref: '#/components/schemas/TransactionID' status: type: string description: | If the status is `open`, then the information was not yet available. Please try again after a few more seconds. If the status is `success` then you can expect the requested information to be present. A status of cancelled means that the user has cancelled the flow. examples: [ success ] enum: [ open, success, cancelled, failure, expired ] issuer_id: $ref: '#/components/schemas/IssuerID' name: maxLength: 200 type: string examples: [ A. van Dijk ] iban: maxLength: 20 pattern: "^NL[0-9]{2}[A-Z-a-z0-9]{4}[0-9]{10}$" type: string examples: [ NL45INGB0000012345 ] description: Note that not all information that was requested is guaranteed to be available from the bank and present in the response. ErrorResponse: title: Error Response type: object properties: status: type: integer format: int32 description: "Response status code, should match HTTP error code" message: type: string description: "High level description of the error that occurred. This description, when present, can be shown to the end user. It might describe that a bank is not available or that the system is offline, or that an unexpected error occurred. In test mode, the API will return more information (targeted at the developer) here then in production mode." code: type: integer format: int32 description: Low level and/or internal error code describing the error. TransactionID: maxLength: 16 minLength: 16 pattern: "^[0-9]+$" type: string description: | A token for this transaction. You should store this with your session data, so that at any point, you can make a callback to the CM api and retrieve the status and/or results. Note that it is not guaranteed that your user will return to you via your merchant_return_url. A connection might be dropped, a user might accidentally close a window, or they might trigger the back button and return that way. This id is the only way you can retrieve any information in that case. IssuerID: pattern: "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$" type: string description: An identifier for the bank. examples: [ RABONL2U ]