---
title: "Create an external transfer with trusted beneficiary"
method: POST
path: "/v2/external_transfers"
tags: ["External Transfers"]
---

# Create an external transfer with trusted beneficiary

`POST /v2/external_transfers`

OAuth scope: `payment.write`

---

Automated creation of a instant external transfer with no user interaction involved once the beneficiary is trusted.

 ---
This endpoint allows you to execute transfers for a given beneficiary. The beneficiary must be trusted for the transfer to be created. The beneficiary can **only** be trusted through the [Qonto web-app](https://app.qonto.com/) (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)).

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.

## Request parameter details

#### `X-Qonto-Idempotency-Key` header

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.

##### 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 `99` characters

##### Debit iban
* `debit_iban`: IBAN of account to debit

##### 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](https://qonto-next.stoplight.io/docs/business-api/branches/create-attachments/b3A6MzU2NjMxMzU-upload-attachment) endpoint. **Note: For SEPA transfers above 30,000 EUR at least one attachment is required**

## Headers

- `X-Qonto-Idempotency-Key` string, required
- `X-Qonto-Staging-Token` string

## Request body

- object
  - `external_transfer` object, required
    - `beneficiary_id` string, uuid, required
    - `debit_iban` string, required
    - `reference` string, required
    - `note` string
    - `currency` string, required — ISO 4217
    - `scheduled_date` string
    - `amount` string, required
    - `attachment_ids` string[]

## Response `200`

returns an external transfer

- object
  - `external_transfer` ExternalTransfer, required
    - `id` string, uuid, required
    - `slug` string, required
    - `debit_iban` string, required — ISO 13616
    - `debit_amount` string, required
    - `debit_amount_cents` string, required
    - `debit_currency` string, required — ISO 4217
    - `beneficiary_id` string, uuid, required
    - `initiator_id` string, uuid, required — 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.
    - `credit_amount` string, required
    - `credit_amount_cents` string, required
    - `credit_currency` string, required — ISO 4217
    - `rate_applied` string
    - `payment_purpose` string — Compulsory for all swift networks
    - `reference` string, required
    - `note` string — 140 characters max
    - `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`
    - `status` string, required — Possible values: `pending` `processing` `canceled` `declined` `settled`
    - `scheduled_date` string, required
    - `created_at` string, required
    - `completed_at` string
    - `processed_at` string
    - `transaction_id` string, uuid

## Other responses

- `422` — Returns errors

---

[API](https://skmtc.net/hiit-consulting-fr/apis/qonto.md) · [All operations](https://skmtc.net/hiit-consulting-fr/apis/qonto/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hiit-consulting-fr/qonto/revisions/25208d6f9deb/schema)