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.

How it works

To create a recipient, you need to validate and confirm their bank account details.

When validating recipient details, we'll verify the format of account and bank identifiers. Where services are available to verify recipient details, we run additional checks. For example, the Confirmation of Payee service in the UK checks the recipient name and account details match.

Once a recipient's details have been validated, you'll confirm the recipient's details. Confirming a validated recipient transitions them to an AUTHORISED state. This means funds can be sent to this recipient.

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.

Validate a recipient

Post/v2/recipients/validate

Use this request to validate a recipient's bank details before you confirm adding them to your account. Specify the recipient's account details including currency, their bank's details including identifiers and country, and payment purpose codes where relevant. For further details on routing information requirements view the payment purpose codes guide.

This endpoint also performs a check on the details of the account for enrolled recipients. Note that details are only checked in production. In sandbox, the validation object in the response will contain mock data.

Request

Sample requestRequest structure

Copy

Copied

curl -i -X POST \
  'https://api.equalsmoney.com/v2/recipients/validate?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountIdentifier": "5555555",
    "bankIdentifier": "123456",
    "name": "John Frank",
    "displayName": "Electrician",
    "type": "individual",
    "defaultReference": "Paying my savings account",
    "currencyCode": "EUR",
    "intermediaryBankIdentifier": "QBLCCCCV",
    "paymentPurposeCode": "BKF",
    "defaultPurpose": "Funding my own account",
    "subscribedEmails": [
      {
        "name": "John",
        "email": "example@email.com"
      }
    ],
    "address": {
      "countryCode": "GB",
      "address": "123 Main St",
      "city": "London",
      "postcode": "SW1A 1AA"
    }
    "bankAddress": {
      "bankName": "Brilliant Bank",
      "fullBankName": "Brilliant Bank Plc",
      "address": "1 Churchill Place, London, E14 5HP",
      "city": "London",
      "postcode": "E14 5HP",
      "countryCode": "GB"
    }
  }'

Copy

Copied

curl -i -X POST \
  'https: //api.equalsmoney.com/v2/recipients/validate?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountIdentifier": "string",
    "bankIdentifier": "string",
    "name": "string",
    "displayName": "string",
    "type": "string",
    "defaultReference": "string",
    "currencyCode": "string",
    "intermediaryBankIdentifier": "string",
    "paymentPurposeCode": "string",
    "defaultPurpose": "string",
    "subscribedEmails": [ // array
      {
        "name": "string",
        "email": "string"
      }
    ],
    "address": { //object
      "countryCode": "string",
      "address": "string",
      "city": "string",
      "postcode": "string"
    },
    "bankAddress": {  //object
      "bankName": "string",
      "fullBankName": "string",
      "address": "string",
      "city": "string",
      "postcode": "string",
      "countryCode": "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
`accountIdentifier` string required	This represents the identifier of the recipient's account, such as an Account Number or IBAN. Example: `55555555`
`bankIdentifier` string required	This represents the identifier of the recipient's bank, such as an a Sort Code, BIC or Routing Number. Example: `123456`
`name` string required	The name of the recipient. Example: `John Frank`
`displayName` string required	Display name for the payee. Example: `Electrician`
`type` string required	The type of account, either `individual`,`business` or `charity`.
`defaultReference` string required	This is the default reference which will be attached to payments made to the recipient if no reference is defined at the point of making a payment. Where reference is used to form part of an account identifier, this field can be used to form part of an Account details check. Example: `Paying my savings account`
`currencyCode` string required	The currency code of which the recipient will receive payments in, ISO-4217 format. Example: `EUR`
`intermediaryBankIdentifier` string	Identifier for intermediary bank. Example: `QBLCCCCV`
`paymentPurposeCode` string	This represents a pre defined purpose for the Payment, more details on payment purpose codes guide. Example: `BKF`
`defaultPurpose` string	Further free text description for the purpose of the payment Example: `Funding my own account`
`subscribedEmails` array	This defines the Email addresses who will be sent notifications of payments to this recipient. This array requires a name and an email as input.
`address` object required	The recipient address object.
`address.countryCode` string required	Country code for the recipient's address. Example: `GB`
`address.address` string required	Street address of the recipient. Example: `123 Main St`
`address.city` string required	City of the recipient's address. Example: `London`
`address.postcode` string required	Postal code of the recipient's address. Example: `SW1A 1AA`
`bankAddress` object required	The recipient's bank address object.
`bankAddress.bankName` string required	Bank name of the recipient's bank. Example: `Brilliant Bank`
`bankAddress.fullBankName` string required	Full bank name of the recipient's bank. Example: `Brilliant Bank PLC`
`bankAddress.address` string required	Street address of the recipient's bank. Example: `123 Main St`
`bankAddress.city` string required	City of the recipient's bank address. Example: `London`
`bankAddress.postcode` string required	Postal code of the recipient's bank address. Example: `SW1A 1AA`
`bankAddress.countryCode` string required	Country code for the recipient's bank address. Example: `GB`

Response

If your request is successful, you will receive a 200 OK response with the following structure:

Sample responseResponse structure

Copy

Copied

{
  "id": "123",
  "accountId": "F60600",
  "status": "unverified",
  "type": "individual",
  "name": "John Frank",
  "displayName": "Electrician",

  "subscribedEmails": [
    {
      "name": "John",
      "email": "example@email.com"
    }
  ],
  "currencyCode": "EUR",
  "accountIdentifier": "GB95SPPV23188424911122",
  "bankIdentifier": "SPPVGB2LXXX",
  "intermediaryBankIdentifier": "QBLCCCCV",
  "paymentPurposeCode": "BKF",
  "defaultPurpose": "Funding my own account",
  "defaultReference": "Paying my savings account",
  "verificationMethod": "sms_otp",
  "address": {
    "countryCode": "GB",
    "address": "123 Main St",
    "city": "London",
    "postcode": "SW1A 1AA"
  },
  "bankAddress": {
    "bankName": "Big Bank",
    "fullBankName": "Big Bank Plc",
    "countryCode": "GB",
    "address": "456 High St",
    "city": "London",
    "postcode": "SW1A 1BB"
  },
 "validation": {
    "nameMatch": false,
    "reason": "String is a close match to the account name",
    "reasonCode": "N200",
    "actualName": "John Frans",
    "displayMessage": "The name provided is a close match to the account name.",
  },
  "dateLastPaid": "string",
  "createdBy": "string",
  "createdAt": "string",
  "updatedBy": "string",
  "updatedAt": "string",
  "archivedAt": "string"
}

Copy

Copied

{
  "id": "string",
  "accountId": "string",
  "status": "string",
  "type": "string",
  "name": "string",
  "displayName": "string",
  "subscribedEmails": [
    {
      "name": "string",
      "email": "string"
    }
  ],
  "currencyCode": "string",
  "accountIdentifier": "string",
  "bankIdentifier": "string",
  "intermediaryBankIdentifier": "string",
  "paymentPurposeCode": "string",
  "defaultPurpose": "string",
  "defaultReference": "string",
  "verificationMethod": "string",
  "address": {
    "countryCode": "string",
    "address": "string",
    "city": "string",
    "postcode": "string"
  },
  "bankAddress": {
    "bankName": "string",
    "fullBankName": "string",
    "countryCode": "string",
    "address": "string",
    "city": "string",
    "postcode": "string"
  },
 "validation": {
    "nameMatch": boolean,
    "reason": "string",
    "reasonCode": "string",
    "actualName": "string",
    "displayMessage": "string",
  },
  "dateLastPaid": "string",
  "createdBy": "string",
  "createdAt": "string",
  "updatedBy": "string",
  "updatedAt": "string",
  "archivedAt": "string"
}

Reason codes

Reason code categories for matching:

N0xx : General match.
N1xx : Account not supported or opt out scenarios.
N2xx : Account details issues (e.g., incorrect number, invalid reference, no name match or close name match).
N3xx : External factors (e.g. account switched).
N5xx : External factors (e.g. downstream server side error).

Equals Reason Code	Reason Message	Long Description	Account Name Returned?
N000	Match	Account details match.	No
N100	Account Not Supported.	The account is not supported for service by the responder.	No
N101	Opted Out Of Service.	The payee has opted out of service.	No
N102	Sort Code Not Supported.	The sort code provided is not supported at the endpoint.	No
N103	Currency Not Supported.	The currency provided does not require account details validation.	No
N104	Market Not Supported.	The Market is currently not supported.	No
N200	Close Match.	The account name closely matches the records but is not exact.	Yes
N201	Account Name Does Not Match.	The account name provided does not match the records.	No
N202	Incorrect Account Number.	The account number provided does not exist.	No
N203	Invalid Customer Reference.	The secondary reference data does not correspond to an account.	No
N204	Account Type Does Not Match Business.	The account type provided does not match the records.	No
N205	Account Type Does Not Match Individual.	The account type provided does not match the records.	No
N206	Business Account Type Does Not Match, Account Name Close.	The account type provided does not match the records, and the name is close-matched.	Yes
N207	Individual Account Type Does Not Match, Account Name Close.	The account type provided does not match the records, and the name is close-matched.	Yes
N300	Account Switched.	The account has been switched to another provider.	No
N400	Recipient predates mandatory validation.	Recipient created before account details validation was available and hasn't undergone current checks.	No
N500	Server side error.	There has been a downstream server side error.	No

Testing Confirmation of Payee (UK Service)

This table lists the predefined test accounts that should be used to execute specific Confirmation of Payee test scenarios in the sandbox. Each account is configured for a different purpose, such as simulating successful matches, close matches, no matches, or invalid configurations. Where the Reference column is N/A, the reference field should be empty in order for the test scenario to work as expected. We will populate the empty reference with the name of the product you are working on.

Test Scenario	Name	accountIdentifier	bankIdentifier	Type	Reference
Matched response testing	Mr Lance Henry	33264517	302414	Individual	N/A
Business matched response	May West Ltd	44264517	302414	Business	N/A
Individual close match testing	Mrs Close Match	34264517	302414	Individual	N/A
Business close match testing	Close Match LT	30264517	302414	Business	N/A
Incorrect account number Test	Mr Lance Henry	99999999	302414	Individual	N/A
Unsupported account type	Max Holding	55124568	302414	Individual	N/A
Switched account status	Matrix Limited	69124578	302414	Business	N/A
Different bankIdentifier testing	Mrs Penny Jones	59124578	302415	Individual	N/A
Common Name Testing	Mr John Smith	79924579	302414	Individual	N/A
Individual SRD testing	Mr Zunaid Malik	44424578	302417	Individual	HOM98765
Business SRD testing	Acme Limited	43424578	302416	Business	ILA-12345
Individual SRD invalid testing	Mr Forest Gump	65724578	302418	Individual	ILA-65432
Business SRD invalid testing	Green Trust Limited	19124578	302414	Business	A-302414
Individual SRD mismatch	Mr Srd Close	29124578	302414	Individual	A-29124578
Business SRD mismatch	Srd Close LTD	39124578	302414	Business	A-39124578

Confirm a recipient

Post/v2/recipients/confirm

Request

Use this request to confirm a validated recipient, which will create them on the specified account. If account details verification is required and fails during the validation step, this must be presented to the customer before confirming the recipient.

Sample requestRequest structure

Copy

Copied

curl -i -X POST \
  'https://api.equalsmoney.com/v2/recipients/8lqccfgmo/confirm?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "verificationMethod": "sms_otp",
  }'

Copy

Copied

curl -i -X POST \
  'https://api.equalsmoney.com/v2/recipients/{recipientId}/confirm?accountId={accountId}' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "verificationMethod": "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`
`recipientId` string required	The ID of the recipient. Allowable values: An existing `recipientId`

Request body schema

Parameter	Description
`verificationMethod` string required	The method used for verifying the recipient. Allowable values: `sms_otp`, `phone`, `email`, `biometrics`, `other`

Response

Upon a successful request, you will receive a 201 Created response, confirming that the recipient creation process has been completed. If you've set up webhooks, you'll receive a RecipientCreated event when this happens.

Sample responseResponse structure

Copy

Copied

{
  "id": "8lqccfgmo",
  "accountId": "F60600",
  "status": "AUTHORISED",
  "type": "individual",
  "name": "John Frank",
  "displayName": "Electrician",
  "subscribedEmails": [
    {
      "name": "John",
      "email": "example@email.com"
    }
  ],
  "currencyCode": "EUR",
  "accountIdentifier": "GB95SPPV23188424911122",
  "bankIdentifier": "SPPVGB2LXXX",
  "intermediaryBankIdentifier": "QBLCCCCV",
  "paymentPurposeCode": "BKF",
  "defaultReference": "Paying my savings account",
  "defaultPurpose": "Funding my own account",
  "verificationMethod": "sms_otp",
  "address": {
    "countryCode": "GB",
    "address": "123 Main St",
    "city": "London",
    "postcode": "SW1A 1AA"
  },
  "bankAddress": {
    "bankName": "Big Bank",
    "fullBankName": "Big Bank Plc",
    "countryCode": "GB",
    "address": "456 High St",
    "city": "London",
    "postcode": "SW1A 1BB"
  },
  "validation": {
	  "nameMatch": false,
	  "reason": "not checked",
	  "reasonCode": "N101",
	  "actualName": "John Frans", 
	  "displayMessage": "Opted out of check",
  },
  "dateLastPaid": "string",
  "createdBy": "string",
  "createdAt": "string",
  "updatedBy": "string",
  "updatedAt": "string",
  "archivedAt": "string"
}

Copy

Copied

{
  "id": "string",
  "accountId": "string",
  "status": "string",
  "type": "string",
  "name": "string",
  "displayName": "string",
  "subscribedEmails": [
    {
      "name": "string",
      "email": "string"
    }
  ],
  "currencyCode": "string",
  "accountIdentifier": "string",
  "bankIdentifier": "string",
  "intermediaryBankIdentifier": "string",
  "paymentPurposeCode": "string",
  "defaultPurpose": "string",
  "defaultReference": "string",
  "verificationMethod": "string",
  "address": {
    "countryCode": "string",
    "address": "string",
    "city": "string",
    "postcode": "string"
  },
  "bankAddress": {
    "bankName": "string",
    "fullBankName": "string",
    "countryCode": "string",
    "address": "string",
    "city": "string",
    "postcode": "string"
  },
  "validation": {
	  "nameMatch": boolean,
	  "reason": "string",
	  "reasonCode": "string",
	  "actualName": "string", 
	  "displayMessage": "string",
  },
  "dateLastPaid": "string",
  "createdBy": "string",
  "createdAt": "string",
  "updatedBy": "string",
  "updatedAt": "string",
  "archivedAt": "string"
}

What's next?

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