> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create external transfers with beneficiaries data
> OAuth scope: `payment.write`
This operation requires [Strong Customer Authentication](/api-reference/business-api/authentication/sca/sca-flows).
Example of SCA usage: [Postman visual flow](https://www.postman.com/qontoteam/workspace/qonto-public-api/flow/6670429eb7bd63003156bd57)
This endpoint will be sunsetted on March 31, 2026.
For SEPA transfers, please use the [Create a SEPA Bulk Transfer](/api-reference/business-api/payments-transfers/sepa-transfers/sepa-bulk-transfers/create) endpoint instead.
The new endpoint works for both trusted and untrusted beneficiaries.
**Solo basic plans**
- Creates a single external transfer with beneficiary data.
- 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.
**Rest of plans**
Creates **up to 400** external transfers with beneficiaries data.
Business rules and validations are applied to each individual transfer synchronously. For instance, transfers above 30,000 EUR require at least one attachment. This validation is performed synchronously so, if the attachment is missing for one transfer, an error will be sent for that transfer (cf. [response payload](#response-errors)) but **the other tranfers will be initiated normally**.
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](https://support-fr.qonto.com/hc/en-us/articles/23947629441681-How-to-make-an-instant-transfer-in-euros-SEPA).
This endpoint requires user interaction for approval of the external transfers. If you want to fully automate external transfers, check our [POST /v2/external_transfers](/api-reference/business-api/payments-transfers/external-transfers/create-an-external-transfer-for-a-trusted-beneficiary) endpoint.
## OpenAPI
````yaml post /v2/external_transfers/checkout
openapi: 3.1.1
info:
version: v2
title: Qonto
servers:
- url: https://thirdparty.qonto.com
description: Production URL
- url: https://thirdparty-sandbox.staging.qonto.co
description: Sandbox URL
security:
- OAuth:
- organization.read
- membership.read
- membership.write
- attachment.write
- internal_transfer.write
- payment.write
- supplier_invoice.write
- supplier_invoice.read
- client_invoices.read
- client_invoice.write
- client.read
- client.write
- product.read
- product.write
- request_review.write
- request_review.read
- team.read
- team.write
- request_transfers.write
- insurance_contract.read
- insurance_contract.write
- card.read
- card.write
- bank_account.write
- beneficiary.trust
- webhook
- payment_link.write
- payment_link.read
- sepa_direct_debit.read
- sepa_direct_debit.write
- terminal.read
- terminal.write
- SecretKey: []
paths:
/v2/external_transfers/checkout:
post:
tags:
- External Transfers (deprecated)
summary: Create external transfers with beneficiaries data
description: >
OAuth scope: `payment.write`
This operation requires [Strong Customer
Authentication](/api-reference/business-api/authentication/sca/sca-flows).
Example of SCA usage: [Postman visual flow](https://www.postman.com/qontoteam/workspace/qonto-public-api/flow/6670429eb7bd63003156bd57)
This endpoint will be sunsetted on March 31, 2026.
For SEPA transfers, please use the [Create a SEPA Bulk Transfer](/api-reference/business-api/payments-transfers/sepa-transfers/sepa-bulk-transfers/create) endpoint instead.
The new endpoint works for both trusted and untrusted beneficiaries.
**Solo basic plans**
- Creates a single external transfer with beneficiary data.
- 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.
**Rest of plans**
Creates **up to 400** external transfers with beneficiaries data.
Business rules and validations are applied to each individual transfer
synchronously. For instance, transfers above 30,000 EUR require at least
one attachment. This validation is performed synchronously so, if the
attachment is missing for one transfer, an error will be sent for that
transfer (cf. [response payload](#response-errors)) but **the other
tranfers will be initiated normally**.
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](https://support-fr.qonto.com/hc/en-us/articles/23947629441681-How-to-make-an-instant-transfer-in-euros-SEPA).
This endpoint requires user interaction for approval of the external transfers. If you want to fully automate external transfers, check our [POST /v2/external_transfers](/api-reference/business-api/payments-transfers/external-transfers/create-an-external-transfer-for-a-trusted-beneficiary) endpoint.
operationId: external_transfers_checkout
parameters:
- $ref: '#/components/parameters/X-Qonto-Staging-Token'
requestBody:
content:
application/json:
schema:
type: object
properties:
vop_proof_token:
type: string
description: >-
Proof token from a bulk payee verification attempt. Use the
token from [bulk verify
payee](/api-reference/business-api/payments-transfers/sepa-transfers/verify-payee/bulk-verify-payee#tag/Bulk-Verify-SEPA-Payee/operation/bulkVerifyPayee)
to opt-out from the verification.
example: proof_1234567890abcdef
debit_iban:
type: string
description: IBAN of account to debit.
external_transfers:
type: array
items:
type: object
properties:
credit_iban:
type: string
description: IBAN of account to credit.
credit_account_name:
type: string
description: The name of the credit account.
credit_account_currency:
type: string
description: >-
Can be either the currency of the `debit_iban` or the
currency of the creditor. Allowed values is only `EUR`
at the moment.
reference:
type: string
description: >-
Transfer reference that can be used to enter transfer
details to further describe the transfer. Maximum
`reference` length is `140` characters.
note:
type: string
currency:
type: string
description: Allowed values is only `EUR` at the moment.
scheduled_date:
type: string
example: '2021-07-12'
description: >-
The transfers will be executed on the `scheduled_date`
(YYYY-MM-DD) at midnight (GMT).
default: Current date or next banking day
amount:
type: string
description: >-
Corresponds to the amount of the transaction in the
`currency` of the bank account. Amounts must be
https://www.w3.org/TR/payment-request/#dfn-valid-decimal-monetary-value.
idempotency_key:
type: string
description: >-
This is a unique string (we advise to use a `uuid`)
that identifies a transfer. This is used by Qonto to
prevent "double spending" by accidentaly replaying the
same API call.
The `idempotency_key` must be the same for all the
call sequence used during the SCA flow :
- For each transfer, the `idempotency_key` is first
set on the initial call, which will trigger the SCA
flow.
- The **same** `idempotency_key` **must** be used on
the final call that includes the SCA token.
This is so because the two calls are actually related
to the **same transfer**.
format: uuid
attachment_ids:
type: array
description: >
You can link up to 5 attachments per transfer by
passing the `attachment_ids` parameter. You can upload
your attachments using our [POST
/v2/attachments](/api-reference/business-api/endpoints/attachments/upload-an-attachment)
endpoint.
**Note: For SEPA transfers above 30,000 EUR at
least one attachment is required**
items:
type: string
format: uuid
required:
- credit_iban
- credit_account_name
- credit_account_currency
- reference
- currency
- amount
required:
- debit_iban
- external_transfers
- vop_proof_token
responses:
'200':
description: Returns the external transfers created.
content:
application/json:
schema:
type: object
properties:
external_transfers:
type: array
items:
$ref: '#/components/schemas/ExternalTransfer'
errors:
description: Detailed errors for each failing transfer in the job.
type: array
items:
type: object
properties:
code:
type: string
detail:
type: string
source:
type: object
properties:
pointer:
type: string
required:
- code
required:
- external_transfers
- errors
examples:
only successes:
value:
external_transfers:
- id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
slug: my-slug
debit_iban: string
debit_amount: '12.55'
debit_amount_cents: '1255'
debit_currency: EUR
initiator_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
beneficiary_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
credit_amount: '12.55'
credit_amount_cents: '1255'
credit_currency: EUR
rate_applied: null
payment_purpose: goods
reference: my-reference
note: Some note
declined_reason: null
status: pending
scheduled_date: '2021-07-12'
created_at: '2021-01-27T22:05:07.000Z'
completed_at: '2021-01-27T22:05:07.000Z'
processed_at: '2021-01-27T22:05:07.000Z'
transaction_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
errors: []
partial successes and errors:
value:
external_transfers:
- id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
slug: my-slug
debit_iban: string
debit_amount: '12.55'
debit_amount_cents: '1255'
debit_currency: EUR
initiator_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
beneficiary_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
credit_amount: '12.55'
credit_amount_cents: '1255'
credit_currency: EUR
rate_applied: null
payment_purpose: goods
reference: my-reference
note: Some note
declined_reason: null
status: pending
scheduled_date: '2021-07-12'
created_at: '2021-01-27T22:05:07.000Z'
completed_at: '2021-01-27T22:05:07.000Z'
processed_at: '2021-01-27T22:05:07.000Z'
transaction_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
errors:
- code: not_found
detail: Bank account was not found
source:
properties:
pointer: /external_transfers/1/debit_iban
only errors:
value:
external_transfers: []
errors:
- code: not_found
detail: Bank account was not found
source:
properties:
pointer: /external_transfers/1/debit_iban
'400':
description: Bad request
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/BadRequestError'
examples:
invalid vop proof token:
value:
errors:
- code: vop_proof_token_invalid
detail: VOP proof token is invalid
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/UnauthorizedError'
examples:
missing vop proof token:
value:
errors:
- code: vop_proof_token_missing
detail: VOP proof token is required
authorization_header_missing:
value:
errors:
- code: authorization_header_missing
detail: authorization header missing
authorization_token_invalid:
value:
errors:
- code: authorization_token_invalid
detail: authorization token invalid
'403':
$ref: '#/components/responses/403-Forbidden'
'422':
description: Returns an unprocessable entity error.
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/UnprocessableEntityError'
x-examples:
Example 1:
errors:
- code: not_found
detail: Bank account was not found
source:
properties:
pointer: /debit_iban
examples:
Invalid IBAN:
value:
errors:
- code: not_found
detail: Bank account was not found
source: null
properties:
pointer: /debit_iban
'428':
$ref: '#/components/responses/428-Precondition-required'
'500':
$ref: '#/components/responses/500-Internal-Server-Error'
deprecated: true
security:
- OAuth:
- payment.write
components:
parameters:
X-Qonto-Staging-Token:
name: X-Qonto-Staging-Token
in: header
description: >-
Required only for Sandbox API requests; to get one, please sign up to
the [Developer Portal](https://developers.qonto.com/).
schema:
type: string
schemas:
ExternalTransfer:
type: object
properties:
id:
type: string
description: this is a description
format: uuid
slug:
type: string
debit_iban:
type: string
description: >-
Can be any of the organization's bank accounts. IBAN formatted ISO
13616.
debit_amount:
type: string
description: The amount that will be debited from your Qonto account.
example: '12.55'
debit_amount_cents:
type: string
description: >-
The amount that will be debited from you Qonto account in an integer
format.
example: '1255'
debit_currency:
type: string
description: Must be EUR. ISO 4217 formatted.
example: EUR
beneficiary_id:
type: string
format: uuid
initiator_id:
type: string
description: >-
ID of the membership that initiated the external transfer.
When the external transfer is initiated through the API, the
initiator is the authenticated membership.
format: uuid
credit_amount:
type: string
description: The amount that the beneficiary will receive.
credit_amount_cents:
type: string
description: The amount that the beneficiary will receive in an integer format.
credit_currency:
type: string
description: >-
Equals debit currency if issued in the SEPA network (only supported
currencies). ISO 4217 format. Allowed value for international
transfers: AUD, CAD, CHF, CNY, CZK, DKK, GBP, HKD, HRK, HUF, ILS,
JPY, NOK, NZD, PLN, RON, SEK, USD.
rate_applied:
type: string
description: >-
Foreign exchange rate applied to your transaction, formatted with 4
digits after comma. Ex: 1,1082
payment_purpose:
type: string
description: Compulsory for all swift networks
example: goods
reference:
type: string
note:
type: string
description: 140 characters max
declined_reason:
type: string
description: >-
Populated only when transfer **status** is declined. Possible
values:
`beneficiary_bic_invalid` `beneficiary_iban_invalid`
`beneficiary_status` `beneficiary_network_rules_error`
`organisation_compliance_reasons` `debit_account_insufficient_funds`
`qonto_processing_failed`
example: beneficiary_bic_invalid
status:
type: string
description: >-
Can contain the following values:
* `pending`: External transfer is created and has not been processed
yet. If transfer is not processed within next minute, it means
either execution date may not been reached yet or we are running
some compliance checks on this transfer.
* `processing`: External transfer processing means account balance
is debited and a transaction has been created. Processing status can
last up to multiple hours until transfer is sent in the network to
the beneficiary.
* `canceled`: When the external transfer is canceled by a user in
the interface. This is a permanent status.
* `declined`: When the external transfer is declined by the
screening service, fraud service or, once sent on the network, for
many various reasons which are listed in [those
guidelines](https://www.europeanpaymentscouncil.eu/sites/default/files/kb/file/2023-11/EPC135-18%20v5.0%20Guidance%20on%20Reason%20Codes%20for%20SCT%20R-transactions.pdf).
This is a permanent status.
* `settled`: When the external transfer is sent to the network,
transfer is settled. This is a permanent status.
example: pending
scheduled_date:
type: string
description: >-
YYYY-MM-DD, indicates when the external transfer was scheduled to be
sent by Qonto.
example: '2021-07-12'
created_at:
type: string
description: UTC, the time at which the external transfer was first recorded
example: '2021-01-27T22:05:07.000Z'
completed_at:
type: string
description: >-
UTC, when the external transfer is in its final state, either
settled or declined.
example: '2021-01-27T22:05:07.000Z'
processed_at:
type: string
description: >-
UTC, when the external transfer has been started to be processed by
Qonto.
example: '2021-01-27T22:05:07.000Z'
transaction_id:
type: string
format: uuid
required:
- id
- slug
- debit_iban
- debit_amount
- debit_amount_cents
- debit_currency
- beneficiary_id
- initiator_id
- credit_amount
- credit_amount_cents
- credit_currency
- reference
- status
- scheduled_date
- created_at
BadRequestError:
type: object
properties:
code:
type: string
description: Error code.
detail:
type: string
description: Human readable error that explains error `code`.
source:
type: object
properties:
pointer:
type: string
description: >-
The property in the request body that caused the error
(optional).
parameter:
type: string
description: The query parameter that caused the error (optional).
required:
- code
- detail
x-examples:
Authorization field missing:
code: bad_request
detail: Authorization field missing
UnauthorizedError:
type: object
properties:
code:
type: string
description: Error code.
detail:
type: string
description: Human readable error that explains error `code`.
required:
- code
- detail
x-examples:
Invalid credentials:
code: unauthorized
detail: Invalid credentials
UnprocessableEntityError:
type: object
properties:
status:
type: string
example: unprocessable entity
code:
type: string
description: Error code.
example: missing_key
detail:
type: string
description: Human readable error that explains error `code`.
example: property is missing
message:
type: string
example: property id is missing
source:
type: object
properties:
pointer:
type: string
description: >-
The property and the item in an array (if applicable) that
causes the error.
example: id
required:
- code
- detail
x-examples:
Missing property:
code: missing_key
detail: property is missing
source:
pointer: /external_transfer/atrribute
ForbiddenResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ForbiddenError'
required:
- errors
ForbiddenError:
type: object
properties:
code:
type: string
description: Error code.
detail:
type: string
description: Human readable error that explains error `code`.
required:
- code
- detail
x-examples:
Insufficient permissions:
code: forbidden
detail: User does not have sufficient permissions for this action.
responses:
403-Forbidden:
description: Returns a forbidden error.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseBody'
examples:
Insufficient permissions:
value:
errors:
- code: forbidden
detail: User does not have sufficient permissions for this action.
428-Precondition-required:
description: Returns SCA precondition required error.
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
detail:
type: string
required:
- code
required:
- errors
examples:
SCA approval is required on the paired device:
value:
errors:
- code: sca_required
detail: You must enable SCA to perform this action
500-Internal-Server-Error:
description: Returns an internal server error.
securitySchemes:
OAuth:
type: oauth2
description: >
Bearer authorization header: `Bearer `, where `` is the
access token received from the authorization server at the end of the
[OAuth 2.0
flow](/get-started/business-api/authentication/oauth/oauth-flow).
flows:
authorizationCode:
refreshUrl: https://oauth.qonto.com/oauth2/token
authorizationUrl: https://oauth.qonto.com/oauth2/auth
scopes:
attachment.read: Retrieve attachments
attachment.write: Upload attachments and remove attachments from transactions
bank_account.write: Create, update and close bank accounts
beneficiary.trust: Trust SEPA beneficiaries
card.read: Retrieve cards
card.write: Create or update cards
client.read: Retrieve clients
client.write: Create clients
client_invoice.write: Create client invoices
client_invoices.read: Retrieve client invoices and credit notes
einvoicing.read: Retrieve e-invoicing settings
embed_auth_link.write: Create Embed auth links
insurance_contract.read: Retrieve insurance contracts
insurance_contract.write: Create and update insurance contracts
internal_transfer.write: >-
Create internal transfers (between 2 Qonto accounts of the same
organization)
international_transfer.write: Create international transfers
membership.read: Retrieve the authentified membership
membership.write: Invite team members
offline_access: Retrieve a refresh token
organization.read: >-
Retrieve organization, bank accounts, transactions, transfers,
beneficiaries, labels, memberships, requests & statements
payment.write: Create external transfers and untrust beneficiaries
payment_link.read: >-
Retrieve payment links, their payments, and the available payment
methods
payment_link.write: >-
Connect to the payment links provider, create and deactivate
payment links
product.read: Retrieve products
product.write: Create products
request_cards.write: Create card requests
request_review.write: Approve or decline requests
request_transfers.write: Create transfer requests
sepa_direct_debit.read: View SEPA Direct Debit payments
sepa_direct_debit.write: Manage SEPA Direct Debit payments
supplier_invoice.read: Retrieve supplier invoices
supplier_invoice.write: Create supplier invoices
team.read: Retrieve teams
team.write: Create teams
terminal.read: View your payment terminals
terminal.write: Configure your terminals and initiate payments
webhook: >-
Receive a notification each time a particular event occurs in
Qonto
tokenUrl: https://oauth.qonto.com/oauth2/token
SecretKey:
type: apiKey
description: cf. [API key](/get-started/business-api/authentication/api-key)
name: Authorization
in: header
````