Skip to main content
POST
/
v2
/
international
/
beneficiaries
/
requirements
List requirements for an international beneficiary
curl --request POST \
  --url https://thirdparty.qonto.com/v2/international/beneficiaries/requirements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "quote_id": "0196edb0-9b6e-7554-9864-d111285a0a44",
  "beneficiary_id": "0d6273cf-e4d0-469a-a3c8-d2196143470c",
  "payload": {
    "currency": "EUR",
    "type": "swift",
    "details": {
      "address": {
        "city": "Paris",
        "country": "FR",
        "postCode": 75009,
        "firstLine": "18 rue du Navarin"
      },
      "legalType": "BUSINESS",
      "swiftCode": "AAABBB00",
      "accountNumber": 123456789,
      "accountHolderName": "John Doe"
    }
  }
}'
{
  "requirements": [
    {
      "type": "swift",
      "fields": [
        {
          "name": "Transfer purpose",
          "group": [
            {
              "key": "transferPurpose",
              "name": "Transfer purpose",
              "type": "text",
              "refresh_requirements_on_change": false,
              "required": true,
              "display_format": "<string>",
              "example": "123456789",
              "min_length": 8,
              "max_length": 20,
              "validation_regexp": "^[0-9]{8,20}$",
              "values_allowed": [
                {
                  "key": "USD",
                  "value": "US Dollar"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
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.

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.

​
Accept-Language
string
default:en

Language to be used to display the requirements. Languages supported: en, it, es, de, fr, pt

Example:

"en"

Body

application/json
​
quote_id
string<uuid>
required

Unique identifier for the quote.

Example:

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

​
payload
object
required

Data collected from the user to create the beneficiary.

​
beneficiary_id
string<uuid>

Unique identifier for the beneficiary (null if creating a new beneficiary).

Example:

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

Response

Returns the list of requirements for the given beneficiary and quote.

​
requirements
object[]