International transfers

International transfers enable you to send money to bank accounts outside the Eurozone, supporting payments in multiple currencies. As each country has its own regulations and requirements, the information needed for international transfers may vary. This guide outlines the available API endpoints for managing international transfers.

Eligibility

Before proceeding with international transfers, you must ensure that the organization is eligible for this service. To check eligibility, send a GET request to /v2/international/eligibility (see Check Eligibility).

Currencies

To find out which currencies are supported for international transfers, you can retrieve a list of available currencies by sending a GET request to /v2/international/currencies (see List Available Currencies).

Quote

To initiate an international transfer, the first step is to obtain a quote. The quote includes key details such as the exchange rate and applicable fees. To get a quote, send a POST request to /v2/international/quotes (see Create a Quote).

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, Qonto will generate a new one; please note that the exchange rate and fees may differ.

Beneficiary

To send an international transfer, you must have a beneficiary set up—a beneficiary is the recipient of the transfer. You can either create a new beneficiary or reuse an existing one. To list existing beneficiaries, send a GET request to /v2/international/beneficiaries. (see List Beneficiaries). In both scenarios (create a new beneficiary or reuse an existing one), you will need to check if the user has to provide more information to complete the transfer. To do so, you have to make a POST request to /v2/international/beneficiaries/requirements(see Check Beneficiary Requirements). This endpoint returns the specific requirements the user must provide to properly configure the beneficiary.

How to collect the beneficiary requirements

The first time you will call this endpoint, you will have to provide:

quote_id: The ID of the quote you obtained in the previous step
beneficiary_id: The ID of the beneficiary if you have one, null otherwise
payload.currency: The currency of the transfer (e.g., EUR, USD, GBP)

Then, you will receive a response containing the requirements the user must provide to properly configure the beneficiary. The requirements field is an array. Each item corresponds to a payment method available for the beneficiary. The user has to select one of them, and you will have to collect the required information for that payment method.For instance, let’s say the requirements looks like that:

{
  "requirements": [
    {
      "type": "swift",
      "fields": [
        {
          "name": "bank_name",
          "group": [{"key":  "bankName", ...}]
        },
        {
          "name": "bank_address",
          "group": [{"key":  "bankAddress", ...}]
        }
      ]
    },
    {
      "payment_method": "aba",
      "fields": [
        {
          "name": "bank_account_identifier",
          "group": [{"key":  "identifier", ...}]
        }
      ]
    }
  ]
}

Then, if the user selects swift, then you will have to collect the following information: bank_name and bank_address. If the user selects aba, then you will have to collect bank_account_identifier.When you collect the required information, you may be asked to call again this endpoint (boolean refresh_requirements_on_change). To do so, you will have to provide the same parameters as before, but you will also have to provide the collected information in the payload field:

payload.type: The payment method selected by the user (e.g., swift, aba)
payload.details: An object containing the collected information, where each key is the name of the field and the value is the value provided by the user.

For instance:

{
  "quote_id": "quote_1234567890",
  "payload": {
    "currency": "EUR",
    "type": "swift",
    "details": {
      "bankName": "Bank of Qonto",
      "bankAddress": "123 Qonto Street, Paris, France"
    }
  }
}

If the field key has a dot (.) in it, it means that the field is a nested object. Example: bank.address.street means that the field is an object with a street property, you should call our api with the following payload:

{
  "quote_id": "quote_1234567890",
  "payload": {
    "currency": "EUR",
    "type": "swift",
    "details": {
      "bank": {
        "address": {
          "street": "123 Qonto Street"
        }
      }
    }
  }
}

You have to iterate over this endpoint until you have collected all the required information.

After you have collected the required information, you have to either:

Update the existing beneficiary by making a PUT request to /v2/international/beneficiaries/{beneficiaryId} (see Update Beneficiary)
Create a new beneficiary by making a POST request to /v2/international/beneficiaries (see Create Beneficiary)

You may receive a new quote after creating or updating a beneficiary. Please use this new one to proceed with the transfer.

Transfer

Once you have a quote and a beneficiary, you can start working on the transfer itself. The first step is to list the required data for the transfer. To do so, you can make a POST request to /v2/international/transfers/requirements (see Check Transfer Requirements).

This endpoint behaves similarly to the beneficiary requirements endpoint.

How to collect the transfer requirements

The first time you will call this endpoint, you will have to provide:

quote_id: The ID of the quote you got in the previous step
target_account_id: The account_id of the beneficiary, obtained after creating or updating the beneficiary

Then, you will receive a response containing the requirements the user must provide to properly configure the transfer. The requirements field is an array, with only one item in it (or 0 if everything is already configured).Like the beneficiary requirements endpoint, you will retrieve all fields that are required to complete the transfer, so you will have to collect the required information from the user.For instance, if the requirements look like this:

{
  "requirements": [
    {
      "type": "transfer",
      "fields": [
        {
          "name": "Transfer purpose",
          "group": [{"key":  "reference", ...}]
        }
      ]
    }
  ]
}

Then, you will have to collect the reference information.When you collect the required information, you may be asked to call again this endpoint (boolean refresh_requirements_on_change). You have to add the key of the field and the value (provided by the user) in the details object.

{
  "quote_id": "quote_1234567890",
  "target_account_id": "beneficiary_1234567890",
  "details": {
    "reference": "My first payment"
  }
}

If the field key has a dot (.) in it, it means that the field is a nested object. Example: source.funds means that the field is an object with a funds property, you should call our api with the following payload:

{
  "quote_id": "quote_1234567890",
  "target_account_id": "beneficiary_1234567890",
  "details": {
    "source": {
      "funds": "My funds"
    }
  }
}

You have to iterate over this endpoint until you have collected all the required information.

After you have collected the required information for the transfer, you can initiate the transfer by making a POST request to /v2/international/transfers (see Create Transfer).

Summary

Here are the steps to follow when working with international transfers:

Check Eligibility: Ensure the organization is eligible for international transfers, by sending a GET request to /v2/international/eligibility.
List Currencies: Retrieve the list of supported currencies by sending a GET request to /v2/international/currencies.
Create a Quote: Obtain a quote for the transfer by sending a POST request to /v2/international/quotes.
List Beneficiaries: Check existing beneficiaries by sending a GET request to /v2/international/beneficiaries.
Check Beneficiary Requirements: Ensure you have the necessary information for the beneficiary by sending a POST request to /v2/international/beneficiaries/requirements.
Create or Update Beneficiary: Either create a new beneficiary by sending a POST request to /v2/international/beneficiaries or update an existing one by sending a PUT request to /v2/international/beneficiaries/{beneficiaryId}.
Check Transfer Requirements: Gather the required information for the transfer by sending a POST request to /v2/international/transfers/requirements.
Create Transfer: Initiate the transfer by sending a POST request to /v2/international/transfers.

Technical guides

Developer Portal

Sandbox

Authentication

PSD2

Webhooks

Payments concepts

Invoicing

Partner mechanisms

Migrations

Troubleshooting

International transfers

Eligibility

Currencies

Quote

Beneficiary

Transfer

Summary

​Eligibility

​Currencies

​Quote

​Beneficiary

​Transfer

​Summary

​Related endpoints

Eligibility

Currencies

Quote

Beneficiary

Transfer

Summary

Related endpoints