Create external transfers with beneficiary data

OAuth scope: payment.write

Accessible only using Strong Customer Authentication.

<!-- theme: none -->

💡 Example of SCA usage: Postman visual flow

---

Solo basic plans

• Create a single instant external transfer with creditor 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

Create a maximum of 400 instant external transfers with creditor data. This API requires user interaction both for creation and approval of the external transfers. If you are interested in machine-to-machine communication without Strong Customer Authentication, check our external transfer with trusted beneficiaries endpoint.

---

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. The idempotency key must be a unique string. We recommend using a UUID.

When there is a 422 error, the easiest way to identify the invalid external transfer in the list, look at the errors[x].source.pointer. The structure of the pointer will be the root key which will always be external_transfers, followed by the index of the ID in the list. For example, /external_transfers/1/amount indicates that the second entry in the external transfers array is unprocessable due to its amount.

Max number of transfers : 400

Attributes details

Initiator ID

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

Debit

• debit_iban: Can be any of the organization's bank accounts. IBAN formatted ISO 13616.
• debit_amount: The amount that will be debited from your Qonto account.
• debit_amount_cents: The amount that will be debited from you Qonto account in an integer format.
• debit_currency: Must be EUR. ISO 4217 formatted.

Credit

• credit_amount: The amount that the creditor will receive.
• credit_amount_cents: The amount that the creditor will receive in an integer format.
• credit_currency: Equals debit currency if issued in the SEPA network (only supported currencies). ISO 4217 format.

FX rate

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

Timestamps

Each external transfer contains three timestamps:

• created_at, UTC, the time at which the external transfer was first recorded.
• processed_at, UTC, when the external transfer has been started to be processed by Qonto.
• completed_at, UTC, when the external transfer is in its final state, either settled or declined.
• scheduled_date, YYYY-MM-DD, indicates when the external transfer was scheduled to be sent by Qonto.

Status

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

Request parameter details

Idempotency_key

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.

Amount and Currency

• The amount 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
• The currency should be EUR.

Reference

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

Debit iban

• debit_iban: IBAN of account to debit

Creditor

• credit_iban: IBAN of account to credit
• credit_account_name: The name of the credit account
• credit_account_currency: Can be either the currency of the debit_iban or the currency of the creditor. Allowed values is only EUR at the moment.

Attachments

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

{
  "external_transfers": [
    {
      "scheduled_date": "2021-07-12"
    }
  ]
}

{
  "external_transfers": [
    {
      "debit_amount": "12.55",
      "debit_amount_cents": "1255",
      "debit_currency": "EUR",
      "payment_purpose": "goods",
      "declined_reason": "beneficiary_bic_invalid",
      "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"
    }
  ]
}