Create recipients - Equals Money Documentation

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 to ensure they are valid. Where services are available to verify recipient details, we run additional checks. All recipients are created with a validation reason code. Only where services are available to perform name checks on the account will the reason code indicate a match, otherwise the reason code will indicate the check has not been performed. The Confirmation of Payee (CoP) service in the UK checks the recipient name and account details match. For SEPA payments, we also support Verification of Payee (VoP) services. This ensures that the recipient’s details are checked at the point of payment, helping reduce the risk of misdirected funds. 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

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",
    "paymentNetwork": "SWIFT",
    "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"
    }
  }'

Query parameters

accountId

string

required

The ID of the account that you’re working with.Allowable values: An existing accountId

Request body schema

accountIdentifier

string

required

This represents the identifier of the recipient’s account, such as an Account Number or IBAN. Example: 55555555

bankIdentifier

string

This represents the identifier of the recipient’s bank, such as an a Sort Code, BIC or Routing Number. This field is required if the accountIdentifier provided is not an IBAN. Example: 123456

name

string

required

The name of the recipient. Example: John Frank

displayName

string

Display name for the payee. Example: Electrician

type

string

required

The type of account, either individual,business or charity.

defaultReference

string

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. This field is required for certain recipients depending on their currencyCode and bankAddress.countryCode. See 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

paymentNetwork

string

This indicates a paymentNetwork preference for the payment to be sent by. If the requested payment network cannot be used, the payment will still be processed via an appropriate network to ensure successful delivery.Allowable values: SWIFT, SEPA.INSTANT, SEPA.CREDITTRANSFER, UKFPS, CHAPS, ACH, WIRETRANSFER

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

Street address of the recipient. Example: 123 Main St

address.city

string

City of the recipient’s address. Example: London

address.postcode

string

Postal code of the recipient’s address. Example: SW1A 1AA

bankAddress

object

The recipient’s bank address object.

bankAddress.bankName

string

Bank name of the recipient’s bank. Example: Brilliant Bank

bankAddress.fullBankName

string

Full bank name of the recipient’s bank. Example: Brilliant Bank PLC

bankAddress.address

string

Street address of the recipient’s bank. Example: 123 Main St

bankAddress.city

string

City of the recipient’s bank address. Example: London

bankAddress.postcode

string

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:

{
  "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",
  "paymentNetwork": "SWIFT",
  "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"
}

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	Recipient validation unavailable.	The service provider did not return a response or the account check was not possible.	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.

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",
  }'

Query parameters

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

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.

{
  "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"
}

What’s next?

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

​How it works

​Validate a recipient

​Request

​Query parameters

​Request body schema

​Response

​Reason codes

​Testing Confirmation of Payee (UK Service)

​Confirm a recipient

​Request

​Query parameters

​Request body schema

​Response

​What’s next?

How it works

Validate a recipient

Request

Query parameters

Request body schema

Response

Reason codes

Testing Confirmation of Payee (UK Service)

Confirm a recipient

Request

Query parameters

Request body schema

Response

What’s next?