These docs are for v2.11. Click to read the latest docs for v2.13.

Onetime Payments

Getting Started

With just two API calls you can initiate and get the payment receipt for your users:

  1. Create a Widget link for one-time payment
  2. Fetching the payment receipt

Step 1: Create Widget Link

Example Request:

POST /onetime/payment

{
  "redirect_uri": "https://my-app.example.com/callback",
  "payment": {
    "creditor": {
      "iban": "DE93300308800013441006",
      "name": "John Doe"
    },
    "amount": {
      "value": 23.99,
      "currency": "EUR"
    },
    "purpose": "Thanks for all the fish.",
  },
  "readout": []
}

Please note that the following parameters are mandatory:

  • redirect_uri: is the address of the location to which the user should be returned back to your application.
  • payment
    • creditor: Includes information about the entity (Natural Person or Business) the payment is directed to
      • iban: is the IBAN of the target account
      • name: is to the name of the recipient
    • amount: defines the money amount to be transferred with this payment
    • purpose: is the purpose text that will be displayed in the receiver's bank.

All other parameters are optional, but some will have a direct effect on the user flow.

If debtor information is passed along within payment, the bank of the end-user will already be preselected in the Widget, so that the user only needs to enter the bank credentials and authorize the account access with Strong Customer Authentication.

    "debtor": {
      "iban": "DE93300308800013441006"
    },

To optimize conversion, you might consider asking the user for their account details before initiating the widget. This will allow the user to skip the bank selection screen and they will be prompted to directly authorize with their bank.

Additionally, using readout with the options ACCOUNTS and TRANSACTIONS allows you to also fetch the account and transaction data of your end-user. In this case, the Widget callback will include an authorization code which can be used to fetch account information. Fetching the account information follows the same procedure as Step 2 in Implementation Guide & Fetching Account & Transaction Data.

Example response:

{
  "location": "https://finx.finleap.cloud/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJoYWhhIjoiaSBtYWRlIHlvdSBsb29rIn0.jk1WqP6S28bNuP5MwwlZHR_5GlksWsEZPMztWUAIiJY",
  "id": "3ca31c37-986a-454e-ad64-8e97143c86bc"
}

Forward the user to the location provided in the response. This can be achieved by using:

  1. an overlay/popup iframe
  2. a redirect in the same or a new window

Step 2:  Fetching the Payment Receipt

Please view the Fetching your Payment Receipt section for a detailed overview.