Skip to main content
POST
Create a Bulk Transfer
Authentication: API key OAuth 2.0
Scope: payment.write Sensitive
Aggregate mode — set is_aggregated: true and provide a reference to group all transfers under a single aggregate transaction on the account. Instead of N individual debit lines, your members see one consolidated entry. The aggregate status updates automatically as child transfers settle. 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 one transfer passes the beneficiary object then SCA will be triggered.
Example of SCA usage: Postman visual flow
You can either provide a beneficiary_id for a known beneficiary or beneficiary data which will create an untrusted beneficiary on the fly. Note:
  • if a beneficiary with the same IBAN already exists, the provided details (such as name) will be updated;
  • this endpoint is not trusting the beneficiary - you can trust a beneficiary through the Qonto app (for more details, please refer to this article) or through this endpoint (available for the Automate your business operations and Embed use cases).
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. By default, transfers will be processed as instant. If instant processing isn’t possible, it will automatically fall back to standard processing. It will be the case if the amount of the individual transfer is above the following thresholds 👇
  • The individual transfer is above 5,000 EUR;
  • More than 20,000 EUR have been sent to this beneficairy within 24 hours.
  • The individual transfer is above 10,000 EUR;
  • More than 50,000 EUR have been sent to this beneficairy within 24 hours.
To learn more about instant transfers, please read this article.

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.

Scopes

payment.write

Create external transfers and untrust beneficiaries

Headers

X-Qonto-2fa-Preference
enum<string>
default:paired-device
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
X-Qonto-MFA
string

Learn more in the SMS OTP Flow.

X-Qonto-Staging-Token
string

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

Body

application/json
vop_proof_token
string
required

Proof token from a bulk payee verification attempt. Use the token from bulk verify payee to opt-out from the verification.

Example:

"proof_1234567890abcdef"

bank_account_id
string<uuid>
required

The ID of the bank account from which the amount will be debited from.

bulk_transfers
object[]
required

List of SEPA transfers to process (up to 400).

Maximum array length: 400
is_aggregated
boolean
default:false

When true, all transfers in the batch appear as a single aggregate transaction on the account instead of N individual debit lines. The aggregate status updates automatically as child transfers settle. Requires reference to be set.

reference
string

Label for the aggregate transaction shown on the account (e.g. "October payroll"). Required when is_aggregated is true. Ignored when is_aggregated is false.

Maximum string length: 255
Example:

"October payroll"

Response

Successfully creates a BulkTransfer for processing

bulk_transfer
object
required