Skip to main content

Payment Initiation Service

This section covers endpoints for initiating money transfers and retrieving information about existing or previously initiated money transfers. These endpoints are only available for users with an active connection. As this already indicates, there are some regulatory requirements to be fulfilled in order to use these endpoints, such as obtaining user consent for each payment initiation.

Requirements​

  • Payment Initiation Service must be enabled for your subscription as it is an optional add-on to the Banking service.
  • The accounts of an established connection used for payment initiation must support payment initiation via the underlying bank interface.
  • Manually uploaded accounts do not support payment initiation by default.
  • Unfortunately, not all banks support payment initiation via their interfaces. Therefore, it is recommended to check the capabilities of the connected bank accounts before attempting to initiate payments. For help, feel free to contact us directly.

Initiating Payments​

To initiate a payment, you can use the Create Payment Initiation Session endpoint. As indicated by our API specification, this endpoint requires both a valid user-id and a valid banklogin-id which are provided through path parameters. Furthermore, the specified bank login must be active and healthy in order to successfully initiate a payment.

You can initiate multiple money transfers in a single request. This is especially useful when debiting one account to pay several recipients at once. When you want to start a payment, just include these details in your request's body:

  • accountId: The internal ID of the account that is to be debited.
  • executionDate: The date you want the transfer to happen (YYYY-MM-DD). It can’t be in the past. If you leave it out, today’s date will be used.
  • exitUrl: The HTTPS link where users should be sent if they leave the payment process.
  • fallbackUrl: The HTTPS link for users if something goes wrong during payment.
  • moneyTransferInfos: A list of details for each transfer you want to make.
  • redirectUrl: The HTTPS link where users go after a successful payment.
  • singleBooking: If you’re making several transfers, set this to true (the default) to group them as one booking, or false to handle each separately.

Please note that the actual execution of the payment depends on the bank's processing times and policies. Also, despite having an active connection, some banks may require additional user authentication or consent for each payment initiation. Accordingly, the user might need to complete a challenge during the payment process.

One more important note: The payment initiation process is not completed when you receive a successful response from the Create Payment Initiation Session endpoint. A successful response only indicates that the payment initiation was started correctly. The actual completion of the payment depends on the bank's processing times and policies. In such cases, we indicate the current status of the payment initiation in the response.

For more information of the possible payment status cases, see the next section.

Retrieving Payment Information​

To get details about existing or previously initiated payments, you can use the Get Money Transfer endpoint. This endpoint requires a valid user-id, banklogin-id, and money-transfer-id as path parameters.

When you initiate a payment, the response you receive provides detailed information about the specified payment order. As specified before, we support multiple money transfers in one go, so the response includes a list of transfers that are part of the payment order, each with its own details. The following fields are included in the response for each transfer:

  • amount: The exact amount that is to be transferred for this payment. This is a numeric value and should match the intended transaction sum.

  • creditor: Details about the recipient of the payment. This object typically includes information such as the name and account details of the person or entity you are sending money to.

  • currency: The currency in which the payment will be made, following the ISO 4217 standard (for example, EUR for Euro or USD for US Dollar). If the currency is not supported, it will be indicated as OTHER.

  • debtor: Information about the sender of the payment. This object contains details about the account from which the money will be debited.

  • purpose: A short description or reason for the payment. This helps both you and the recipient understand the context of the transaction.

Besides these fields for each transfer, the response also includes a status field indicating the overall state of the payment initiation, which helps you track the progress of your transfer. The possible values for the status field are:

status:

  • OPEN: The payment initiation has been created and is awaiting further processing.
  • PENDING: The payment initiation is being processed by the bank and yet to be completed.
  • SUCCESSFUL: The payment was completed successfully.
  • NOT_SUCCESSFUL: The payment could not be completed.
  • DISCARDED: The payment initiation was canceled or discarded.

By reviewing these fields, you can follow the journey of your payment from initiation to completion, ensuring transparency and clarity at every step.

One final note: As the completion of payments happens asynchronously at the bank's side, the previously established connection must remain active and healthy to track the payment status effectively. We cannot acquire any updates on the payment's status if the connection is inactive or has been revoked.