Create recipients (deprecated)

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

info

Effective February 12th, 2025, the legacy recipient endpoint /v2/recipients will be retired. All new recipients must be created through the new Create Recipients flow.

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.