/ Guides / Payments / Send payments / Create recipients

Create recipients

Create a recipient (beneficiary) so that you can create an order. A recipient represents an account that you're making a payment to.

Validate a bank account

Post/v2/recipients/validate/account

Request

Use this request to validate a recipient's bank details before you add them to your account. Note that details are only checked in production. In sandbox, you'll receive a response with mock data.

info

By default, this endpoint isn't enabled. If you'd like to use it, please contact your account manager.

Sample requestRequest structure
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/recipients/validate/account?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "country": "GB",
    "iban": "GB24BKEN10000031510604",
    "number": "31510604",
    "code": "100000"
}'
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/recipients/validate/account?accountId={accountId}' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "country": "string",
    "iban": "string",
    "number": "string",
    "code": "string"
  }'

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that you're working with.

Allowable values:
An existing accountId

Request body schema

Parameter Description
country
string
required		 The recipient's country, in ISO 3166-1 alpha-2 format.

Allowable values:
<= 2 characters
iban
string		 The recipient's International Bank Account Number (IBAN).

Allowable values:
<= 100 characters
number
string		 The recipient's bank account number.

Allowable values:
A valid string
code
string		 The recipient's bank sort code.

Allowable values:
A valid string

Response

If your request is successful, you'll receive a 200 response.

Sample responseResponse structure
Copy
Copied
{
  "countryCode": "GB",
  "nationalId": "100000",
  "accountNumber": "31510604",
  "status": "PASS",
  "comment": "",
  "recommendedNatId": "100000",
  "recommendedAcct": "31510604",
  "recommendedBIC": "GB24BKEN",
  "ref": "20231024154938548",
  "group": "",
  "branchDetails": [
    {
      "bankName": "Brilliant Bank",
      "branch": "",
      "street": "223 Glossop Road",
      "city": "London",
      "postZip": "N14 4ES",
      "region": "England",
      "country": "UNITED KINGDOM",
      "codeDetails": {
        "codeName1": "BIC",
        "codeValue1": "GB24BKEN",
        "codeName2": "CHIPS",
        "codeValue2": "",
        "codeName3": "BIC-4",
        "codeValue3": "BBUK",
        "codeName4": "Sort Code",
        "codeValue4": "12-34-56"
      },
      "additionalData": {
        "ssiAvailable": "Y",
        "payServiceAvailable": "Y",
        "contactsAvailable": "N",
        "messageAvailable": "N",
        "holidayAvailable": "Y"
      },
      "sepaDetails": {
        "ctStatus": "NO",
        "ddStatus": "No",
        "bbStatus": "No"
      },
      "bankToken": "znDAyLqxw64BXqqADwZecO4ubOoDSRBJ65OTdTQqdIHPp4ZywR4ETPPTXpqZ"
    }
  ],
  "headOfficeDetails": {
    "bankName": "Brilliant Bank",
    "branch": "",
    "street": "223 Glossop Road",
    "city": "London",
    "postZip": "N14 4ES",
    "region": "England",
    "country": "UNITED KINGDOM",
    "codeDetails": {
      "codeName1": "BIC",
      "codeValue1": "GB24BKEN",
      "codeName2": "CHIPS",
      "codeValue2": "",
      "codeName3": "BIC-4",
      "codeValue3": "BBUK",
      "codeName4": "Sort Code",
      "codeValue4": "12-34-56"
    },
    "additionalData": {
      "ssiAvailable": "Y",
      "payServiceAvailable": "Y",
      "contactsAvailable": "N",
      "messageAvailable": "N",
      "holidayAvailable": "Y"
    }
  },
  "paymentBicDetails": {
    "bankName": "Brilliant Bank",
    "branch": "",
    "street": "223 Glossop Road",
    "city": "London",
    "postZip": "N14 4ES",
    "region": "England",
    "country": "UNITED KINGDOM",
    "codeDetails": {
      "codeName1": "BIC",
      "codeValue1": "GB24BKEN",
      "codeName2": "CHIPS",
      "codeValue2": "",
      "codeName3": "BIC-4",
      "codeValue3": "BBUK",
      "codeName4": "Sort Code",
      "codeValue4": "12-34-56"
    },
    "additionalData": {
      "ssiAvailable": "Y",
      "payServiceAvailable": "Y",
      "contactsAvailable": "N",
      "messageAvailable": "N",
      "holidayAvailable": "Y"
    },
    "branchTypeLabel": "IBAN BIC Branch"
  },
  "bic8": "N",
  "dataStore": "N",
  "noBranch": "N",
  "isoAddr": "N",
  "payBranchType": "D",
  "freeToken": "yKgweVyX4Tk2coBwK63WRr1jjV9SYMavKMNG0QUnnHWKJUauIHEREvW4UwvQ"
}
Copy
Copied
{
  "countryCode": "string",
  "nationalId": "string",
  "accountNumber": "string",
  "status": "string",
  "comment": "string",
  "recommendedNatId": "string",
  "recommendedAcct": "string",
  "recommendedBIC": "string",
  "ref": "string",
  "group": "string",
  "branchDetails": [
    {
      "bankName": "string",
      "branch": "string",
      "street": "string",
      "city": "string",
      "postZip": "string",
      "region": "string",
      "country": "string",
      "codeDetails": {
        "codeName1": "string",
        "codeValue1": "string",
        "codeName2": "string",
        "codeValue2": "string",
        "codeName3": "string",
        "codeValue3": "string",
        "codeName4": "string",
        "codeValue4": "string"
      },
      "additionalData": {
        "ssiAvailable": "string",
        "payServiceAvailable": "string",
        "contactsAvailable": "string",
        "messageAvailable": "string",
        "holidayAvailable": "string"
      },
      "sepaDetails": {
        "ctStatus": "string",
        "ddStatus": "string",
        "bbStatus": "string"
      },
      "bankToken": "string"
    }
  ],
  "headOfficeDetails": {
    "bankName": "string",
    "branch": "string",
    "street": "string",
    "city": "string",
    "postZip": "string",
    "region": "string",
    "country": "string",
    "codeDetails": {
      "codeName1": "string",
      "codeValue1": "string",
      "codeName2": "string",
      "codeValue2": "string",
      "codeName3": "string",
      "codeValue3": "string",
      "codeName4": "string",
      "codeValue4": "string"
    },
    "additionalData": {
      "ssiAvailable": "string",
      "payServiceAvailable": "string",
      "contactsAvailable": "string",
      "messageAvailable": "string",
      "holidayAvailable": "string"
    }
  },
  "paymentBicDetails": {
    "bankName": "string",
    "branch": "string",
    "street": "string",
    "city": "string",
    "postZip": "string",
    "region": "string",
    "country": "string",
    "codeDetails": {
      "codeName1": "string",
      "codeValue1": "string",
      "codeName2": "string",
      "codeValue2": "string",
      "codeName3": "string",
      "codeValue3": "string",
      "codeName4": "string",
      "codeValue4": "string"
    },
    "additionalData": {
      "ssiAvailable": "string",
      "payServiceAvailable": "string",
      "contactsAvailable": "string",
      "messageAvailable": "string",
      "holidayAvailable": "string"
    },
    "branchTypeLabel": "string"
  },
  "bic8": "string",
  "dataStore": "string",
  "noBranch": "string",
  "isoAddr": "string",
  "payBranchType": "string",
  "freeToken": "string"
}

Create a recipient

Post/v2/recipients

Before you start

The format of your request will vary depending on the bank details that you wish to provide. For more information about the type of details to provide depending on the country that you're sending money to, see About preferred recipient details.

Type of bank details Field Usage Example
BIC bic N/A MIDLGB22XXX
Account number accountNumber N/A 31510604
Sort code bankCode N/A 100000
Canadian routing number accountNumber This should be pre-fixed to the account number, with a hyphen separating the two. 099912345-123456789012
BSB number accountNumber This should be pre-fixed to the account number, with a hyphen separating the two. 033547-123456789
IFSC defaultReference This should be formatted as IFSC followed by the IFSC itself, then any other reference captured. IFSC ABCD0123456
CLABE accountNumber N/A. 014027000000000008

Request

Use this request to create a recipient.

You'll need to provide one of the following:

  • an accountNumber and bankCode
  • an accountNumber and bic
  • an iban
info

Even in sandbox, you should always provide valid bank details or you'll receive a 500 response. You can find a list of test IBANs, account numbers, and sort codes here.

The following example is for a payment using an accountNumber and a bankCode.

Sample requestRequest structure
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/recipients?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountNumber": "31510604",
    "bankCode": "100000",
    "name": "Rosie Richards",
    "defaultPurpose": "Exchange",
    "currency": "GBP",
    "verificationMethod": "phone",
    "recipientAddress": {
      "country": "GB",
      "address": "123 Main Street",
      "city": "London",
      "postcode": "E1ZW6"
    }
  }'
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/recipients?accountId={accountId}' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountNumber": "string",
    "bankCode": "string",
    "name": "string",
    "paymentPurposeCode": "string",
    "defaultPurpose": "string",
    "currency": "string",
    "verificationMethod": "string",
    "recipientAddress": {
      "country": "string",
      "address": "string",
      "city": "string",
      "postcode": "string"
    }
  }'

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that you're creating a recipient for.

Allowable values:
An existing accountId

Request body schema

Parameter Description
accountNumber
string
required if no IBAN is provided		 The recipient's bank account number.

Allowable values:
<= 34 characters
bankCode
string
required if no BIC or IBAN is provided		 The recipient's bank code (sort code).

Allowable values:
^\d{6}$
bic
string
required if no sort code or IBAN is provided		 The recipient's Bank Identifier Code (BIC).

Allowable values:
^[a-zA-Z]{6}[a-zA-Z0-9]{2}([a-zA-Z0-9]{3})?
iban
string
required if no account number is provided		 The recipient's International Bank Account Number (IBAN).

Allowable values:
<= 100 characters
name
string
required		 The recipient's name.

Allowable values:
<= 256 characters
friendlyName
string		 An internal reference name for the recipient.

Allowable values:
<= 256 characters
intermediaryBankIdentifier
string		 The Bank Identifier Code (BIC) of the intermediary bank.

Allowable values:
<= 256 characters
paymentPurposeCode
string		 The payment purpose code, in ISO 200222 format.

Allowable values:
<= 256 characters
email
string		 The recipient's email address. Where possible, this will be the address that is notified when a payment is in progress.

Allowable values:
<= 256 characters
defaultPurpose
string
required		 The purpose of the payment.

Allowable values:
<= 256 characters
currency
string
required		 The currency that the recipient should receive, in ISO 4217 format.

Allowable values:
3 characters
verificationMethod
string
required		 The method that you've used to verify the identity of the recipient.

Allowable values:
phone, sms_otp, biometrics, other
recipientAddress
object
required		 Details about the recipient's address.

Allowable values:
A valid recipientAddress object containing the following fields: country, address, city, postcode
recipientAddress.country
string
required		 The recipient's country, in ISO 3166-1 alpha-2 format.

Allowable values:
2 characters (^[A-Z]{2}$)
recipientAddress.address
string		 The recipient's street address.

Allowable values:
<= 256 characters
recipientAddress.city
string		 The recipient's city.

Allowable values:
<= 256 characters
recipientAddress.postcode
string		 The recipient's postal or ZIP code.

Allowable values:
<= 36 characters

Response

If your request is successful, you'll receive a 201 response containing a recipientId and a UNIX timestamp. If you've set up webhooks, you'll receive a RecipientCreated event when this happens.

Sample responseResponse structure
Copy
Copied
{
  "recipientId": "9lsag2a6x",
  "timestamp": 1707228994282
}
Copy
Copied
{
  "recipientId": "string",
  "timestamp": number
}
info

If you receive a 500 response, this is most likely due to the bank details provided being incorrect. Make sure you're using valid bank details. You can find a list of test IBANs, account numbers, and sort codes here

For more detailed information about this request and its response, see the API reference.

What's next?

Now that you've created a recipient, you're ready to create a currency quote.