Skip to main content
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 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 transfer for a beneficiary Creates a single SEPA transfer for a given beneficiary. Endpoint: Example Request: 
{
  "vop_proof_token": "proof_1234567890abcdef",
  "transfer": {
    "bank_account_id": "0a8df251-de2a-4394-bffc-6b9d9795700d",
    "beneficiary_id": "3e4d5f6a-7b8c-9d0e-1f2a-3b4c5d6e7f8a",
    "reference": "string",
    "note": "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. Alternatively, provide an inline beneficiary object with name and iban.
  • Ensure that the amount is correctly formatted and within transaction limits.
  • This endpoint requires SCA unless the beneficiary is trusted.
  • For transfers exceeding €30,000, at least one attachment is required.
Case 2: Create a SEPA bulk transfer Create up to 400 transfers at once. 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: Example Request: 
{
  "vop_proof_token": "proof_1234567890abcdef",
  "bank_account_id": "0a8df251-de2a-4394-bffc-6b9d9795700d",
  "bulk_transfers": [
    {
      "beneficiary_id": "3e4d5f6a-7b8c-9d0e-1f2a-3b4c5d6e7f8a",
      "client_transfer_id": "0cd90e5a-2c03-4ab6-81a8-d48818026e58",
      "reference": "string",
      "note": "string",
      "scheduled_date": "2021-07-12",
      "amount": "string",
      "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 SEPA transfers at once.
  • 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 transfers.

​
What does it look like?