Adding payments

One of the most straightforward and implemented use case of our Business API is adding Payment capabilities within a partner’s app.

If you already help your customers manage their invoices, automating your payments can help with 2 use cases:

💸 optimize providers bills payment thanks to bulk payouts (up to 400 bills) in 1 click

✨ reduce payment delays and increase recoveries success rate by sharing a payment link with clients bills

—

Let’s focus on 💸 Optimize providers bills payment

If you already show your customers the invoices they’ll need to pay within your interface, the one thing missing is a “Pay” button which will allow to pay up to 400 bills in just 1 click from their Qonto account

The magic behind hitting that “Pay” button involves:

1. Retrieving the transfers beneficiaries’ data
2. Setting up SCA
3. Creating the transfers

Below the key steps to consider for a smooth implementation:

​

1. Retrieve the transfers Beneficiaries’ Data

​

a. Finding existing beneficiaries’ data

Objective:

• Determine if the beneficiary is already trusted or if new details need to be added.

Endpoints

• GET /v2/beneficiaries: use this endpoint in order to retrieve the list of beneficiaries for the authenticated organization.

If the beneficiary is not trusted on Qonto, you can add it via API, but your customers will need trust it themselves directly from the app → https://support-fr.qonto.com/hc/en-us/articles/23947644174993-How-can-I-mark-a-payee-as-trustworthy#h_925061f25d

​

b. Add Beneficiaries if necessary (coming soon)

​

2. Set up SCA (Strong Customer Authentication)

Objective:

• Secure the transaction to ensure it is authorized by the account holder or administrators

Steps:

• Choose Authentication Method:
  • Trusted Device: User will receive a push notification on their registered device (computer or mobile) to approve the transaction.
  • Passkeys: User will receive a text message with a link to approve or set up a passkey.

Initiate SCA:

• Specify Method: Use the X-Qonto-2fa-Preference header in your request to choose between paired-device or passkey.
• Start SCA Process: When initiating a sensitive transaction, provide this header to indicate the preferred method of authentication.

Endpoints for SCA:

• GET /v2/sca_sessions/<sca-session-token> : Poll this endpoint to check the status of the SCA session. The session will return one of three outcomes:
  • waiting: User has not yet approved the action.
  • deny: User has refused the action or the session expired (after 15 minutes).
  • allow: User has authorized the action.

Functional Details:

• Ensure the user is aware of the pending authorization and guide them on how to approve the transaction.
• Handle scenarios where the user may not receive the notification or delays in response.

Example Headers for Authorization:

{
  "X-Qonto-2fa-Preference": "paired-device",
  "X-Qonto-Sca-Session-Token": "<sca-session-token>"
}

​

3. Create Transfers

Objective:

• Execute the transfer, either to a trusted beneficiary or with new beneficiary data.

Case 1: Create a unit external transfer for a trusted beneficiary

Creates a single instant external transfer for a given trusted beneficiary, without any user interaction required.

Endpoint:

• POST /v2/external_transfers

Example Request:

{
  "external_transfer": {
    "beneficiary_id": "0a8df251-de2a-4394-bffc-6b9d9795700d",
    "debit_iban": "string",
    "reference": "string",
    "note": "string",
    "currency": "string",
    "scheduled_date": "2021-07-12",
    "amount": "string",
    "attachment_ids": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
  }
}

Functional Details:

• Verify that the beneficiary_id is correct and corresponds to the intended recipient.
• Ensure that the amount and currency fields are correctly formatted and within transaction limits.
• SCA is not necessary here.

Case 2: Create external transfers with beneficiary data

Create up to 400 transfers with beneficiary data. This action requires human validation before processing.

If the person that initiates the transfers is neither owner nor administrator of the account, they can prepare the transfers and then send a request so that the owner or administrator can validate via SCA - please look into the roles that can be set in Qonto → https://support-fr.qonto.com/hc/en-us/articles/23947722927249-What-are-the-different-roles-available

Endpoint:

• POST /v2/external_transfers/checkout

Example Request:

{
  "debit_iban": "string",
  "external_transfers": [
    {
      "credit_iban": "string",
      "credit_account_name": "string",
      "credit_account_currency": "string",
      "reference": "string",
      "note": "string",
      "currency": "string",
      "scheduled_date": "2021-07-12",
      "amount": "string",
      "idempotency_key": "0cd90e5a-2c03-4ab6-81a8-d48818026e58",
      "attachment_ids": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ]
    }
  ]
}

Functional Details:

• Ensure that you are SCA-enrolled
• Double-check all beneficiary details to prevent errors in the transaction.
• Confirm the transaction details with the user before submission to ensure accuracy and prevent unauthorized transfers.

General Functional Considerations:\

• Log all transaction attempts with timestamps and status for audit and troubleshooting purposes.
• Solo basic plans are not allowed to do bulk transfers. If a bulk transfer is attempted, it will fail and an error will be returned.
• For the rest of the plans, you can create up to 400 instant external transfers with beneficiaries data.
• Be reminded that the number of monthly transfers included in the customer’s Qonto plan is listed here.
• This endpoint requires user interaction for approval of the external transfers. If you want to fully automate external transfers, check our /v2/external_transfers endpoint.

​

What does it look like?