Create an international beneficiary

curl --request POST \
  --url https://thirdparty.qonto.com/v2/international/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "quote_id": "0196edb0-9b6e-7554-9864-d111285a0a44",
  "payload": {
    "currency": "EUR",
    "type": "aba",
    "details": {
      "address": {
        "city": "Paris",
        "country": "FR",
        "postCode": 75009,
        "firstLine": "18 rue du Navarin"
      },
      "swiftCode": "AAABBB00",
      "accountNumber": 123456789,
      "accountHolderName": "John Doe"
    }
  }
}
'

{
  "beneficiary": {
    "id": "0d6273cf-e4d0-469a-a3c8-d2196143470c",
    "name": "John Doe",
    "country": "US",
    "currency": "USD",
    "payment_type": "aba",
    "account_identifier": "123456789",
    "bank_identifier": "AAABBB00",
    "branch_identifier": "123456789"
  },
  "quote": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "PENDING",
    "created_at": "2025-01-01T08:00:00.000Z",
    "expired_at": "2025-01-01T08:00:00.000Z",
    "source_amount": {
      "currency": "EUR",
      "value": "100.00"
    },
    "target_amount": {
      "currency": "USD",
      "value": "110.00"
    },
    "rate": 1.1,
    "fees": {
      "total_amount": {
        "currency": "EUR",
        "value": "10.10"
      },
      "details": [
        {
          "currency": "EUR",
          "value": "10.10"
        }
      ]
    }
  },
  "target_account_id": "123456"
}

POST

international

beneficiaries

Create an international beneficiary

curl --request POST \
  --url https://thirdparty.qonto.com/v2/international/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "quote_id": "0196edb0-9b6e-7554-9864-d111285a0a44",
  "payload": {
    "currency": "EUR",
    "type": "aba",
    "details": {
      "address": {
        "city": "Paris",
        "country": "FR",
        "postCode": 75009,
        "firstLine": "18 rue du Navarin"
      },
      "swiftCode": "AAABBB00",
      "accountNumber": 123456789,
      "accountHolderName": "John Doe"
    }
  }
}
'

{
  "beneficiary": {
    "id": "0d6273cf-e4d0-469a-a3c8-d2196143470c",
    "name": "John Doe",
    "country": "US",
    "currency": "USD",
    "payment_type": "aba",
    "account_identifier": "123456789",
    "bank_identifier": "AAABBB00",
    "branch_identifier": "123456789"
  },
  "quote": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "PENDING",
    "created_at": "2025-01-01T08:00:00.000Z",
    "expired_at": "2025-01-01T08:00:00.000Z",
    "source_amount": {
      "currency": "EUR",
      "value": "100.00"
    },
    "target_amount": {
      "currency": "USD",
      "value": "110.00"
    },
    "rate": 1.1,
    "fees": {
      "total_amount": {
        "currency": "EUR",
        "value": "10.10"
      },
      "details": [
        {
          "currency": "EUR",
          "value": "10.10"
        }
      ]
    }
  },
  "target_account_id": "123456"
}

The payload object for this endpoint is the same as the one used in the List Beneficiary requirements endpoint.

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

quote_id

string<uuid>

required

The quote unique identifier

Example:

"0196edb0-9b6e-7554-9864-d111285a0a44"

payload

object

required

Show child attributes

payload.currency

string

required

Currency the beneficiary receives money in (ISO 4217 format, alpha 3).

Example:

"EUR"

payload.type

enum<string>

required

Payment method the beneficiary receives money in (aba or swift_code)

Available options:

aba,

swift_code

Example:

"aba"

payload.details

object

required

Beneficiary detail contains all the information needed to create a beneficiary. The data is dynamic and should be retrieved through the beneficiary requirements endpoint.

Example:

{
  "address": {
    "city": "Paris",
    "country": "FR",
    "postCode": 75009,
    "firstLine": "18 rue du Navarin"
  },
  "swiftCode": "AAABBB00",
  "accountNumber": 123456789,
  "accountHolderName": "John Doe"
}

Response

Returns the international beneficiary created

beneficiary

object

Show child attributes

beneficiary.id

string<uuid>

required

Unique identifier of the beneficiary

Example:

"0d6273cf-e4d0-469a-a3c8-d2196143470c"

beneficiary.name

string

required

The beneficiary's name

Example:

"John Doe"

beneficiary.country

string

required

The beneficiary's country

Example:

"US"

beneficiary.currency

string

required

The currency of the beneficiary's bank account

Example:

"USD"

beneficiary.payment_type

string

required

The payment method the beneficiary receives money in

Example:

"aba"

beneficiary.account_identifier

string

required

The account identifier of the beneficiary

Example:

"123456789"

beneficiary.bank_identifier

string

The bank identifier of the beneficiary

Example:

"AAABBB00"

beneficiary.branch_identifier

string

The branch identifier of the beneficiary

Example:

"123456789"

quote

object

Show child attributes

quote.id

string<uuid>

required

Unique identifier for the quote.

Example:

"123e4567-e89b-12d3-a456-426614174000"

quote.status

enum<string>

required

the quote status

Available options:

PENDING,

FUNDED,

EXPIRED,

ACCEPTED

Example:

"PENDING"

quote.created_at

string<date-time>

required

The date and time when the quote was created.

Example:

"2025-01-01T08:00:00.000Z"

quote.expired_at

string<date-time>

required

The date and time when the quote will expire

Example:

"2025-01-01T08:00:00.000Z"

quote.source_amount

object

required

Show child attributes

quote.source_amount.currency

string

required

The currency of the source account.

Example:

"EUR"

quote.source_amount.value

string

required

The amount to be transferred from the source account.

Example:

"100.00"

quote.target_amount

object

required

Show child attributes

quote.target_amount.currency

string

required

The currency of the target account.

Example:

"USD"

quote.target_amount.value

string

required

The amount to be transferred to the target account.

Example:

"110.00"

quote.rate

number

required

The exchange rate applied to the transfer.

Example:

1.1

quote.fees

object

required

Show child attributes

quote.fees.total_amount

object

required

Show child attributes

quote.fees.total_amount.currency

string

required

Fees currency

Example:

"EUR"

quote.fees.total_amount.value

string

required

Fees amount value

Example:

"10.10"

quote.fees.details

object[]

Show child attributes

quote.fees.details.currency

string

required

Fees currency

Example:

"EUR"

quote.fees.details.value

string

required

Fees amount value

Example:

"10.10"

target_account_id

string

The ID of the beneficiary's target account

Example:

"123456"

Update an international beneficiary Delete an international beneficiary

⌘I

Business API

Onboarding API

Create an international beneficiary

Authorizations

Headers

Body

Response