Create external transfers with beneficiaries data

curl --request POST \
  --url https://thirdparty.qonto.com/v2/external_transfers/checkout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "vop_proof_token": "proof_1234567890abcdef",
  "debit_iban": "<string>",
  "external_transfers": [
    {
      "credit_iban": "<string>",
      "credit_account_name": "<string>",
      "credit_account_currency": "<string>",
      "reference": "<string>",
      "currency": "<string>",
      "amount": "<string>",
      "note": "<string>",
      "scheduled_date": "2021-07-12",
      "idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "attachment_ids": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    }
  ]
}
'

{
  "external_transfers": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "slug": "<string>",
      "debit_iban": "<string>",
      "debit_amount": "12.55",
      "debit_amount_cents": "1255",
      "debit_currency": "EUR",
      "beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "initiator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "credit_amount": "<string>",
      "credit_amount_cents": "<string>",
      "credit_currency": "<string>",
      "reference": "<string>",
      "status": "pending",
      "scheduled_date": "2021-07-12",
      "created_at": "2021-01-27T22:05:07.000Z",
      "rate_applied": "<string>",
      "payment_purpose": "goods",
      "note": "<string>",
      "declined_reason": "beneficiary_bic_invalid",
      "completed_at": "2021-01-27T22:05:07.000Z",
      "processed_at": "2021-01-27T22:05:07.000Z",
      "transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "errors": [
    {
      "code": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

External Transfers (deprecated)

Create external transfers with beneficiaries data

OAuth scope: payment.write

This operation requires Strong Customer Authentication.

Example of SCA usage: Postman visual flow

This endpoint will be sunsetted on March 31, 2026. For SEPA transfers, please use the Create a SEPA Bulk Transfer 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) 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 👇

Untrusted beneficiary

The individual transfer is above 5,000 EUR;
More than 20,000 EUR have been sent to this beneficairy within 24 hours.

Trusted beneficiary

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.

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 endpoint.

POST

external_transfers

checkout

Create external transfers with beneficiaries data

curl --request POST \
  --url https://thirdparty.qonto.com/v2/external_transfers/checkout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "vop_proof_token": "proof_1234567890abcdef",
  "debit_iban": "<string>",
  "external_transfers": [
    {
      "credit_iban": "<string>",
      "credit_account_name": "<string>",
      "credit_account_currency": "<string>",
      "reference": "<string>",
      "currency": "<string>",
      "amount": "<string>",
      "note": "<string>",
      "scheduled_date": "2021-07-12",
      "idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "attachment_ids": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    }
  ]
}
'

{
  "external_transfers": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "slug": "<string>",
      "debit_iban": "<string>",
      "debit_amount": "12.55",
      "debit_amount_cents": "1255",
      "debit_currency": "EUR",
      "beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "initiator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "credit_amount": "<string>",
      "credit_amount_cents": "<string>",
      "credit_currency": "<string>",
      "reference": "<string>",
      "status": "pending",
      "scheduled_date": "2021-07-12",
      "created_at": "2021-01-27T22:05:07.000Z",
      "rate_applied": "<string>",
      "payment_purpose": "goods",
      "note": "<string>",
      "declined_reason": "beneficiary_bic_invalid",
      "completed_at": "2021-01-27T22:05:07.000Z",
      "processed_at": "2021-01-27T22:05:07.000Z",
      "transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "errors": [
    {
      "code": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

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.

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"

debit_iban

string

required

IBAN of account to debit.

external_transfers

object[]

required

Show child attributes

external_transfers.credit_iban

string

required

IBAN of account to credit.

external_transfers.credit_account_name

string

required

The name of the credit account.

external_transfers.credit_account_currency

string

required

Can be either the currency of the debit_iban or the currency of the creditor. Allowed values is only EUR at the moment.

external_transfers.reference

string

required

Transfer reference that can be used to enter transfer details to further describe the transfer. Maximum reference length is 140 characters.

external_transfers.currency

string

required

Allowed values is only EUR at the moment.

external_transfers.amount

string

required

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.

external_transfers.note

string

external_transfers.scheduled_date

string

default:Current date or next banking day

The transfers will be executed on the scheduled_date (YYYY-MM-DD) at midnight (GMT).

Example:

"2021-07-12"

external_transfers.idempotency_key

string<uuid>

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.

external_transfers.attachment_ids

string<uuid>[]

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 endpoint.
Note: For SEPA transfers above 30,000 EUR at least one attachment is required

Response

Returns the external transfers created.

external_transfers

object[]

required

Show child attributes

external_transfers.id

string<uuid>

required

this is a description

external_transfers.slug

string

required

external_transfers.debit_iban

string

required

Can be any of the organization's bank accounts. IBAN formatted ISO 13616.

external_transfers.debit_amount

string

required

The amount that will be debited from your Qonto account.

Example:

"12.55"

external_transfers.debit_amount_cents

string

required

The amount that will be debited from you Qonto account in an integer format.

Example:

"1255"

external_transfers.debit_currency

string

required

Must be EUR. ISO 4217 formatted.

Example:

"EUR"

external_transfers.beneficiary_id

string<uuid>

required

external_transfers.initiator_id

string<uuid>

required

ID of the membership that initiated the external transfer.
When the external transfer is initiated through the API, the initiator is the authenticated membership.

external_transfers.credit_amount

string

required

The amount that the beneficiary will receive.

external_transfers.credit_amount_cents

string

required

The amount that the beneficiary will receive in an integer format.

external_transfers.credit_currency

string

required

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.

external_transfers.reference

string

required

external_transfers.status

string

required

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. 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"

external_transfers.scheduled_date

string

required

YYYY-MM-DD, indicates when the external transfer was scheduled to be sent by Qonto.

Example:

"2021-07-12"

external_transfers.created_at

string

required

UTC, the time at which the external transfer was first recorded

Example:

"2021-01-27T22:05:07.000Z"

external_transfers.rate_applied

string

Foreign exchange rate applied to your transaction, formatted with 4 digits after comma. Ex: 1,1082

external_transfers.payment_purpose

string

Compulsory for all swift networks

Example:

"goods"

external_transfers.note

string

140 characters max

external_transfers.declined_reason

string

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"

external_transfers.completed_at

string

UTC, when the external transfer is in its final state, either settled or declined.

Example:

"2021-01-27T22:05:07.000Z"

external_transfers.processed_at

string

UTC, when the external transfer has been started to be processed by Qonto.

Example:

"2021-01-27T22:05:07.000Z"

external_transfers.transaction_id

string<uuid>

errors

object[]

required

Detailed errors for each failing transfer in the job.

Show child attributes

errors.code

string

required

errors.detail

string

errors.source

object

Show child attributes

errors.source.pointer

string

Create an external transfer for a trusted beneficiary Create an internal transfer

⌘I

Business API

Onboarding API

Create external transfers with beneficiaries data

Authorizations

Headers

Body

Response