/ Guides / Payments / Tutorial / Create a recipient

Step 1: create a recipient

To send funds to a third party, you first need to create a recipient (beneficiary) by validating account ownership and confirming the recipient. Once you submit your validation request, we’ll verify the account details you’ve provided.

info

validate a recipient also allows you to create a recipient in an unverified state.

In this example, we're using a bank account number and bank identifier, but you can also supply an account number and BIC, or an IBAN. See the API reference for more information.

SandboxProduction
Copy
Copied
curl -i -X POST \
  'https://api-sandbox.equalsmoney.com/v2/recipients/validate?accountId={accountId}' \
  -H 'Authorization: ApiKey {apiKey}' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountIdentifier": "31510604",
    "bankIdentifier": "100000",
    "name": "William Walker",
    "displayName": "Electrician",
    "type": "business",
    "defaultReference": "William Walker",
    "currencyCode": "USD",
    "intermediaryBankIdentifier": "QBLCCCCV",
    "paymentPurposeCode": "BKFE",
    "defaultPurpose": "Purpose of the payment",
    "subscribedEmails": [
      {
        "name": "William Walker",
        "email": "test@example.com"
      }
    ],
    "address": {
      "countryCode": "GB",
      "address": "123 Fake Street",
      "city": "London",
      "postcode": "SW1A 1AA"
    }
  }'
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/recipients/validate?accountId={accountId}' \
  -H 'Authorization: ApiKey {apiKey}' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountIdentifier": "31510604",
    "bankIdentifier": "100000",
    "name": "William Walker",
    "displayName": "Electrician",
    "type": "business",
    "defaultReference": "William Walker",
    "currencyCode": "USD",
    "intermediaryBankIdentifier": "QBLCCCCV",
    "paymentPurposeCode": "BKFE",
    "defaultPurpose": "Purpose of the payment",
    "subscribedEmails": [
      {
        "name": "William Walker",
        "email": "test@example.com"
      }
    ],
    "address": {
      "countryCode": "GB",
      "address": "123 Fake Street",
      "city": "London",
      "postcode": "SW1A 1AA"
    }
  }'

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

You should confirm a recipient to finalise the process of creating a recipient. This will transition the recipient's status to AUTHORISED, allowing payments to be made to them. See the API reference for more information.

SandboxProduction
Copy
Copied
curl -i -X POST \
  'https://api-sandbox.equalsmoney.com/v2/recipients/{recipientId}/confirm?accountId={accountId}' \
  -H 'Authorization: ApiKey {apiKey}' \
  -H 'Content-Type: application/json' \
  -d '{
    "verificationMethod": "phone",
    "sessionId": "string",
    "token": "string"
  }'
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/recipients/{recipientId}/confirm?accountId={accountId}' \
  -H 'Authorization: ApiKey {apiKey}' \
  -H 'Content-Type: application/json' \
  -d '{
    "verificationMethod": "phone",
    "sessionId": "string",
    "token": "string"
  }'

If your request is successful, you'll receive a 201 response and a RecipientCreated webhook.

Copy
Copied
{
  "accountIdentifier": "55555555",
  "bankIdentifier": "395744",
  "name": "William Walker",
  "displayName": "Electrician",
  "type": "business",
  "defaultReference": "William Walker",
  "currencyCode": "USD",
  "intermediaryBankIdentifier": "QBLCCCCV",
  "paymentPurposeCode": "BKFE",
  "defaultPurpose": "Purpose of the payment",
  "subscribedEmails": [
    {
      "name": "William Walker",
      "email": "test@example.com"
    }
  ],
  "address": {
    "countryCode": "GB",
    "address": "123 Fake Street",
    "city": "London",
    "postcode": "SW1A 1AA"
  },
  "id": "string",
  "status": "AUTHORISED",
  "validation": {
    "nameMatch": true,
    "reason": "string",
    "reasonCode": "N000",
    "actualName": "William Walker"
  },
  "bankAddress": {
    "bankName": "Barclays Bank",
    "fullBankName": "Barclays Bank Plc",
    "address": "1 Churchill Place, London, E14 5HP",
    "city": "London",
    "postcode": "E14 5HP",
    "countryCode": "GB"
  },
  "dateLastPaid": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "archivedAt": "2019-08-24T14:15:22Z",
  "createdBy": "string",
  "updatedBy": "string",
  "verificationMethod": "phone"
}

Next