Getting Started

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

Create a Widget link for ongoing payments
Fetching the payment receipt

Step 1: Create Widget Link

Example Request:

{
  "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.",
  },
  "save_secrets": false,
  "user_id": "[email protected]"
}

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.
user_id: is a unique identifier given to each user. Additional payments can be initiated with the same user through the widget with the same user_id.

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

The save_secrets parameter is set to false by default. This means that users will receive the choice to save their credentials through the Widget. By setting this field to true the credentials are securely saved on the finX platform without asking for the user's consent.

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.

Alternatively, if you are using Introduction to Multibanking, it is possible to issue a payment from a previously synchronized account by specifying the corresponding account_id in the request.

{
  "account_id": "A12345.6"
}

🚧
The account_id is mutually exclusive from payment.debtor.iban and should not be specified at the same time.

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:

an overlay/popup iframe
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.