> ## 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 international transfer
> OAuth scope: `international_transfer.write`
Creates a new international transfer.
Example of SCA usage: [Postman visual flow](https://www.postman.com/qontoteam/workspace/qonto-public-api/flow/6670429eb7bd63003156bd57)
This endpoint is still in **beta**. Please get in touch with our team if you have any question or feedback: [here](https://getqonto.atlassian.net/servicedesk/customer/portals).
The `details` object for this endpoint is the same as the one used in the [List Transfer
requirements](./list-transfer-requirements) endpoint.
Quotes are only valid for a limited time, so it’s recommended to proceed with the transfer promptly after obtaining
one. If the quote expires, the transfer will be created with a new generated quote; please note that the exchange
rate and fees may differ.
## OpenAPI
````yaml post /v2/international/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/international/transfers:
parameters:
- $ref: '#/components/parameters/X-Qonto-Staging-Token'
post:
tags:
- International Transfers
summary: Create an international transfer
description: >-
OAuth scope: `international_transfer.write`
Creates a new international transfer.
Example of SCA usage: [Postman visual flow](https://www.postman.com/qontoteam/workspace/qonto-public-api/flow/6670429eb7bd63003156bd57)
This endpoint is still in **beta**. Please get in touch with our team if
you have any question or feedback:
[here](https://getqonto.atlassian.net/servicedesk/customer/portals).
operationId: createInternationalTransfer
parameters:
- $ref: '#/components/parameters/X-Qonto-2fa-Preference'
- name: X-Qonto-Idempotency-Key
in: header
required: true
description: >-
This endpoint requires an UUID as idempotency key. Learn more in
[Idempotent Requests](/get-started/general/idempotent-requests).
schema:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
- $ref: '#/components/parameters/X-Qonto-Sca-Session-Token'
- $ref: '#/components/parameters/X-Qonto-MFA'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateInternationalTransferRequest'
responses:
'200':
description: Returns the created international transfer.
content:
application/json:
schema:
type: object
properties:
transfer:
$ref: '#/components/schemas/InternationalTransferPayload'
'400':
$ref: '#/components/responses/400-Bad-request'
'401':
$ref: '#/components/responses/401-Unauthorized'
'403':
$ref: '#/components/responses/403-Forbidden'
'404':
$ref: '#/components/responses/404-Not-Found'
'412':
$ref: '#/components/responses/412-Precondition-Failed'
'422':
$ref: '#/components/responses/422-Unprocessable-Entity'
'428':
$ref: '#/components/responses/428-Precondition-required'
'500':
$ref: '#/components/responses/500-Internal-Server-Error'
security:
- OAuth:
- international_transfer.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
X-Qonto-2fa-Preference:
name: X-Qonto-2fa-Preference
in: header
description: >-
Learn more in [Strong Customer
Authentication](/api-reference/business-api/authentication/sca/sca-flows).
schema:
type: string
enum:
- paired-device
- passkey
- mock
- sms-otp
default: paired-device
X-Qonto-Sca-Session-Token:
name: X-Qonto-Sca-Session-Token
in: header
description: >-
Learn more in [Strong Customer
Authentication](/api-reference/business-api/authentication/sca/sca-flows).
schema:
type: string
X-Qonto-MFA:
name: X-Qonto-MFA
in: header
description: >-
Learn more in the [SMS OTP
Flow](/api-reference/business-api/authentication/sca/sca-flows#sms-otp-flow).
schema:
type: string
schemas:
CreateInternationalTransferRequest:
type: object
properties:
beneficiary_id:
type: string
format: uuid
description: The beneficiary unique identifier
example: 0196edb0-9b6e-7554-9864-d111285a0a44
bank_account_id:
type: string
format: uuid
description: The bank account unique identifier
example: 0196edb0-9b6e-7554-9864-d111285a0a42
quote_id:
type: string
format: uuid
description: The quote unique identifier
example: 0196edb0-9b6e-7554-9864-d111285a0a43
target_account_id:
type: string
description: >-
The target account unique identifier. Retrieved after the
beneficiary is created or updated
example: '123456'
attachment_ids:
type: array
items:
type: string
format: uuid
description: List of attachment IDs associated with the transaction
example:
- 0196edb0-9b6e-7554-9864-d111285a0a40
details:
type: object
description: >
Transfer detail contains all the information needed to create a
transfer.
The data is dynamic and should be retrieved through the transfer
requirements endpoint.
example:
reference: 'Payment for invoice #123'
source_amount:
type: object
properties:
currency:
type: string
description: The currency of the source account.
example: EUR
value:
type: string
description: The amount to be transferred from the source account.
example: '100.00'
required:
- currency
- value
target_amount:
type: object
properties:
currency:
type: string
description: The currency of the target account.
example: EUR
value:
type: string
description: The amount to be transferred from the target account.
example: '100.00'
required:
- currency
- value
required:
- beneficiary_id
- quote_id
- bankAccount_id
- details
- target_account_id
- source_amount
- target_amount
InternationalTransferPayload:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier of the international transfer
example: 0d6273cf-e4d0-469a-a3c8-d2196143470c
beneficiary_id:
type: string
format: uuid
description: Unique identifier of the beneficiary
example: 0196edb0-9b6e-7554-9864-d111285a0a44
bank_account_id:
type: string
format: uuid
description: Unique identifier of the bank account
example: 0196edb0-9b6e-7554-9864-d111285a0a42
source_amount:
type: object
properties:
currency:
type: string
description: The currency of the source account.
example: EUR
value:
type: string
description: The amount to be transferred from the source account.
example: '100.00'
required:
- currency
- value
target_amount:
type: object
properties:
currency:
type: string
description: The currency of the target account.
example: USD
value:
type: string
description: The amount to be transferred from the target account.
example: '110.00'
required:
- currency
- value
status:
type: string
enum:
- TRANSACTION_STATUS_PROCESSING
- TRANSACTION_STATUS_CANCELLED
- TRANSACTION_STATUS_DECLINED
- TRANSACTION_STATUS_SETTLED
- TRANSACTION_STATUS_RETURNED
description: the transfer status
example: TRANSACTION_STATUS_PROCESSING
BadRequestResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/BadRequestError'
required:
- errors
UnauthorizedResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/UnauthorizedError'
required:
- errors
ForbiddenResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ForbiddenError'
required:
- errors
NotFoundError:
type: object
properties:
code:
type: string
description: Error code.
detail:
type: string
description: Human readable error that explains error `code`.
source:
type: object
properties:
parameter:
type: string
description: The parameter that causes the error.
required:
- code
- detail
x-examples:
Object not found:
code: not_found
detail: Object not found
source:
parameter: id
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
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
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
401-Unauthorized:
description: Returns an unauthorized error.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponseBody'
examples:
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-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.
404-Not-Found:
description: Returns a not found error.
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/NotFoundError'
412-Precondition-Failed:
description: Invalid SCA session token
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: A human readable message describing the error
example: Invalid SCA session token
code:
type: string
description: The error code
example: invalid_sca_session
422-Unprocessable-Entity:
description: Returns an unprocessable entity error.
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/UnprocessableEntityError'
x-examples:
Example 1:
errors:
- code: missing_key
detail: reference is missing
source:
pointer: /external_transfer/reference
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
````