Create a Bulk Transfer

OAuth scope: payment.write

This operation requires Strong Customer Authentication, except when all transfers include a beneficiary_id and all beneficiaries are trusted, in which case SCA is not required. However, if at least transfer passes the beneficiary object then SCA will be triggered.

Example of SCA usage: Postman visual flow

Creates a batch of SEPA transfers for asynchronous processing. If the payload is valid, a BulkTransfer is created and returned, which can be polled via GET v2/sepa/bulk_transfers/:id.

You can either provided a beneficiary_id for a known beneficiary or beneficiary data which will create a beneficiary on the fly. Note: If a beneficiary with the same IBAN already exists, the provided details, such as name, will be updated.

Business rules and validations are applied to each individual transfer after the BulkTransfer is created. For instance, transfers above 30,000 EUR require at least one attachment. This validation is performed asynchronously, meaning the BulkTransfer will be created, but if the attachment is missing, the result for that transfer will contain an error.

POST

sepa

bulk_transfers

curl --request POST \
  --url https://thirdparty.qonto.com/v2/sepa/bulk_transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Qonto-Idempotency-Key: <x-qonto-idempotency-key>' \
  --data '{
  "bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "bulk_transfers": [
    {
      "beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "beneficiary": {
        "name": "Alice In Wonderland",
        "iban": "DE91100000000123456789",
        "bic": "DEUTDEDDXXX",
        "email": "beneficiary@example.com",
        "activity_tag": "atm"
      },
      "reference": "Inventory",
      "amount": "100.50",
      "scheduled_date": "2023-12-25",
      "note": "Inventory goods for restaurant in Paris",
      "attachment_ids": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "client_transfer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "initiator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2025-04-22T12:00:00Z",
  "updated_at": "2025-04-22T12:00:00Z",
  "total_count": 400,
  "completed_count": 200,
  "failed_count": 150,
  "pending_count": 50,
  "results": [
    {
      "client_transfer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "transfer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "errors": [
        {
          "errors": [
            {
              "code": "<string>",
              "detail": "<string>"
            }
          ]
        }
      ],
      "status": "pending"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authorization header: Bearer <token>, where <token> is the access token received from the authorization server at the end of the OAuth 2.0 flow.

Headers

X-Qonto-Staging-Token

string

Required only for Sandbox API requests; to get one, please sign up to the Developer Portal.

X-Qonto-2fa-Preference

enum<string>

default:paired-device

Learn more in Strong Customer Authentication.

Available options:

paired-device,

passkey,

mock,

sms-otp

X-Qonto-Idempotency-Key

string

required

Learn more in Idempotent Requests.

Example:

"123e4567-e89b-12d3-a456-426614174000"

X-Qonto-Sca-Session-Token

string

Learn more in Strong Customer Authentication.

X-Qonto-MFA

string

Learn more in the SMS OTP Flow.

Body

application/json

Response

200

application/json

Successfully creates a BulkTransfer for processing

The response is of type object.

Get Bulk Transfer List SEPA beneficiaries

curl --request POST \
  --url https://thirdparty.qonto.com/v2/sepa/bulk_transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Qonto-Idempotency-Key: <x-qonto-idempotency-key>' \
  --data '{
  "bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "bulk_transfers": [
    {
      "beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "beneficiary": {
        "name": "Alice In Wonderland",
        "iban": "DE91100000000123456789",
        "bic": "DEUTDEDDXXX",
        "email": "beneficiary@example.com",
        "activity_tag": "atm"
      },
      "reference": "Inventory",
      "amount": "100.50",
      "scheduled_date": "2023-12-25",
      "note": "Inventory goods for restaurant in Paris",
      "attachment_ids": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "client_transfer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "initiator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2025-04-22T12:00:00Z",
  "updated_at": "2025-04-22T12:00:00Z",
  "total_count": 400,
  "completed_count": 200,
  "failed_count": 150,
  "pending_count": 50,
  "results": [
    {
      "client_transfer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "transfer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "errors": [
        {
          "errors": [
            {
              "code": "<string>",
              "detail": "<string>"
            }
          ]
        }
      ],
      "status": "pending"
    }
  ]
}

Qonto APIs

Business API

Onboarding API

Qonto Embed Web SDK

Create a Bulk Transfer

Authorizations

Headers

Body

Response