> ## 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 an external transfer for a trusted beneficiary
> OAuth scope: `payment.write`
This endpoint will be sunsetted on March 31, 2026.
For SEPA transfers, please use the [Create a SEPA Transfer](/api-reference/business-api/payments-transfers/sepa-transfers/sepa-transfers/create) endpoint instead.
The new endpoint works for both trusted and untrusted beneficiaries.
Creates a single external transfer for a given **trusted** beneficiary, without any user interaction required.
The beneficiary must be trusted for the transfer to be created. The beneficiary can **only** be trusted through the Qonto app (for more details, please refer to [this article](https://support-fr.qonto.com/hc/en-us/articles/23947644174993-How-can-I-mark-a-payee-as-trustworthy#h_925061f25d)).
By default, the transfer 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 transfer is above the following thresholds:
- The 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).
## OpenAPI
````yaml post /v2/external_transfers
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:
post:
tags:
- External Transfers (deprecated)
summary: Create an external transfer for a trusted beneficiary
description: >-
OAuth scope: `payment.write`
This endpoint will be sunsetted on March 31, 2026.
For SEPA transfers, please use the [Create a SEPA Transfer](/api-reference/business-api/payments-transfers/sepa-transfers/sepa-transfers/create) endpoint instead.
The new endpoint works for both trusted and untrusted beneficiaries.
Creates a single external transfer for a given **trusted** beneficiary,
without any user interaction required.
The beneficiary must be trusted for the transfer to be created. The
beneficiary can **only** be trusted through the Qonto app (for more
details, please refer to [this
article](https://support-fr.qonto.com/hc/en-us/articles/23947644174993-How-can-I-mark-a-payee-as-trustworthy#h_925061f25d)).
By default, the transfer 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 transfer is above the following
thresholds:
- The 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).
operationId: create_external_transfer
parameters:
- $ref: '#/components/parameters/X-Qonto-Idempotency-Key'
- $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 payee verification attempt or skip
verification request. Use the token from [verify
payee](/api-reference/business-api/payments-transfers/sepa-transfers/verify-payee#tag/Verify-SEPA-Payee/operation/verifyPayee).
example: proof_1234567890abcdef
external_transfer:
type: object
properties:
beneficiary_id:
type: string
description: '`id` of the trusted beneficiary.'
format: uuid
debit_iban:
type: string
description: IBAN of account to debit.
reference:
type: string
description: >-
Can be used to enter transfer details to further
describe the transfer. Maximum `reference` length is
`99` 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 transfer 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.
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:
- beneficiary_id
- debit_iban
- reference
- currency
- amount
required:
- external_transfer
- vop_proof_token
responses:
'200':
description: Returns the external transfer created.
content:
application/json:
schema:
type: object
properties:
external_transfer:
$ref: '#/components/schemas/ExternalTransfer'
required:
- external_transfer
'400':
$ref: '#/components/responses/400-Bad-request'
'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'
required:
- errors
examples:
Beneficiary is not trusted:
value:
errors:
- code: untrusted_beneficiary
detail: >-
External transfers can only be initiated to trusted
beneficiaries
source:
properties:
pointer: /external_transfer/beneficiary_id
'`debit_iban` cannot be found':
value:
errors:
- code: not_found
detail: Bank account was not found
source:
properties:
pointer: /external_transfer/debit_iban
'`reference` is missing':
value:
errors:
- code: missing_key
detail: reference is missing
source:
pointer: /external_transfer/reference
'`amount` is missing':
value:
errors:
- code: missing_key
detail: amount is missing
source:
pointer: /external_transfer/amount
'`currency` is missing':
value:
errors:
- code: missing_key
detail: currency is missing
source:
pointer: /external_transfer/currency
IBAN is not in SEPA:
value:
errors:
- code: iban_not_sepa
detail: Beneficiary is not in SEPA
source:
pointer: /external_transfer/beneficiary_id
Not enough funds in the account:
value:
errors:
- code: insufficient_funds
detail: The account has insufficient funds
source:
pointer: /external_transfer/debit_iban
'`attachment_id` cannot be found':
value:
errors:
- code: not_found
detail: >-
Attachment not found
id=6cc7f2dd-ea0d-4cc2-ba30-f3e1ce0a8eb4
source:
pointer: /external_transfer/attachment_ids/1
'`attachment_ids` exceeds max limit':
value:
errors:
- code: above_max_size
detail: attachment_ids cannot be greater than 5
source:
pointer: /external_transfer/attachment_ids
invalid vop proof token:
value:
errors:
- code: vop_proof_token_invalid
detail: VOP proof token is invalid
'500':
$ref: '#/components/responses/500-Internal-Server-Error'
deprecated: true
security:
- OAuth:
- payment.write
components:
parameters:
X-Qonto-Idempotency-Key:
name: X-Qonto-Idempotency-Key
in: header
required: true
description: >-
Learn more in [Idempotent
Requests](/get-started/general/idempotent-requests).
schema:
type: string
example: 123e4567-e89b-12d3-a456-426614174000
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
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
BadRequestResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/BadRequestError'
required:
- errors
ForbiddenResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ForbiddenError'
required:
- errors
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
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:
400-Bad-request:
description: Returns a bad request error.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseBody'
examples:
Authorization field missing:
value:
errors:
- code: bad_request
detail: Authorization field missing
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.
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
````