API GuideAPI ReferenceChangelog
API GuideAPI ReferenceChangelog
  • API Reference
  • Webhook Reference
    • POSTReferral Created Event
    • POSTCustomer Status Updated Event
    • POSTVirtual Account Status Updated Event
    • POSTPayment Status Updated Event
    • POSTThird Party Customer Status Updated Event
LogoLogo
API ReferenceCustomersAPI IntegrationRecipients

Add a new recipient

POST
/v2/customers/:customer_id/recipients
POST
/v2/customers/:customer_id/recipients
1curl -X POST https://api.redpincompany.com/v2/customers/cust_123456789/recipients \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "name": "Ahmed Al Mansoori",
6  "type": "Individual",
7  "country_code": "ARE",
8  "customer_own_account": "no",
9  "address": {
10    "address_line": "Office 2101, Jumeirah Bay X2 Tower",
11    "city": "Dubai",
12    "state": "Dubai",
13    "post_code": "000000"
14  },
15  "recipient_bank_details": {
16    "currency": "AED",
17    "iban": "AE070331234567890123456"
18  },
19  "nick_name": "Ahmed UAE",
20  "email": "ahmed.mansoori@example.com",
21  "phone_number": "+971-501234567",
22  "mobile_number": "+971-501234567",
23  "client_reference_id": "recipient-123",
24  "payment_reference": "Invoice#4567"
25}'
Try it
1{
2  "client_reference_id": "recipient-123",
3  "recipient_id": "1668758"
4}
To make a money transfer, you'll need to add details of the Recipient's account. There are a number of parameters which you can use to specify this account, but generally, recipient data objects consist of: General Information - Recipient personal details - Legal structure (Individual/ Corporation) - Contact information - Country Code (ISO3166-1 alpha-3) This [OAuth 2.0 Authenticated](/api-guide/getting-started/authentication#oauth-20-authentication) Add Recipient API allows you to register a recipient with their personal and bank details.
Was this page helpful?
Previous

Get recipient details

Next
Built with
Get recipient details

To make a money transfer, you’ll need to add details of the Recipient’s account. There are a number of parameters which you can use to specify this account, but generally, recipient data objects consist of:

General Information

  • Recipient personal details
  • Legal structure (Individual/ Corporation)
  • Contact information
  • Country Code (ISO3166-1 alpha-3)

This OAuth 2.0 Authenticated Add Recipient API allows you to register a recipient with their personal and bank details.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

customer_idstringRequired
Unique identifier for the customer to whom the recipient is being added.

Request

This endpoint expects an object.
namestringRequired
Name of the recipient as per their bank records.
typeenumRequired
Organisational type of a recipient; whether an Individual or Corporate.
Allowed values:
country_codestringRequired
Three-letter [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code representing the recipient's country.
customer_own_accountenumRequired
Recipient to be added is customer own account or not.
Allowed values:
addressobjectRequired
recipient_bank_detailsobjectRequired
Recipient bank account details vary by country. For example, an IBAN is sufficient for most European and Nordic countries. However, for the United States, you must provide an account number, routing code type, routing code value, and the bank's country code. You must also specify the `currency` of the recipient's bank account using a three-letter ISO 4217 currency code (e.g., `GBP` for British Pound). The following are the four supported combinations of recipient bank account details: - `iban` - `account_number` and `swift_code` - `account_number`, `swift_code`, and `routing_code_value` - `account_number`, `routing_code_type`, `routing_code_value`, and `bank_country_code` **Examples:** 1. IBAN: ```json {"currency": "AED", "iban": "AE070331234567890123456"} ``` 2. Account number and Swift code: ```json {"currency": "AED", "account_number": "12345678", "swift_code": "BOMLAEADXXX"} ``` 3. Account number, Swift code, and Routing code value: ```json {"currency": "AED", "account_number": "12345678", "swift_code": "BOMLAEADXXX", "routing_code_value": "601613"} ``` 4. Account number, Routing code type, Routing code value, and Bank country code: ```json {"currency": "AED", "account_number": "12345678", "routing_code_type": "SORT", "routing_code_value": "601613", "bank_country_code": "ARE"} ```
nick_namestringOptional
Optional nickname for the recipient. Useful for quick searches and display purposes.
emailstringOptional
Email address of a recipient, which may be used in case of an issue with a transaction.
phone_numberstringOptional
Recipient's phone number.
mobile_numberstringOptional
Recipient's mobile number.
client_reference_idstringOptional
A Reference Id that you can assign to this recipient, for your records.
payment_referencestringOptional
Optional payment reference required by some accounts. This reference should be used for future payments. It should not contain any special character.
confirm_recipientobjectOptional
Container for confirmation of recipient details. This object is required only when the initial API call fails due to a Confirmation of Payee (CoP) check failure. If the failure is related to CoP, the API response will include `request_identifier` and `event_id`, which must be used in the subsequent retry request along with the appropriate `customer_action`.

Response

Recipient added successfully
client_reference_idstring
Reference Id assigned to this recipient.
recipient_idstring
Unique identifier for the recipient.

Errors

Recipient bank account details vary by country.

For example, an IBAN is sufficient for most European and Nordic countries. However, for the United States, you must provide an account number, routing code type, routing code value, and the bank’s country code.

You must also specify the currency of the recipient’s bank account using a three-letter ISO 4217 currency code (e.g., GBP for British Pound).

The following are the four supported combinations of recipient bank account details:

  • iban
  • account_number and swift_code
  • account_number, swift_code, and routing_code_value
  • account_number, routing_code_type, routing_code_value, and bank_country_code

Examples:

  1. IBAN: 
    1{"currency": "AED", "iban": "AE070331234567890123456"}
  2. Account number and Swift code: 
    1{"currency": "AED", "account_number": "12345678", "swift_code": "BOMLAEADXXX"}
  3. Account number, Swift code, and Routing code value: 
    1{"currency": "AED", "account_number": "12345678", "swift_code": "BOMLAEADXXX", "routing_code_value": "601613"}
  4. Account number, Routing code type, Routing code value, and Bank country code: 
    1{"currency": "AED", "account_number": "12345678", "routing_code_type": "SORT", "routing_code_value": "601613", "bank_country_code": "ARE"}
Name of the recipient as per their bank records.
Recipient to be added is customer own account or not.
Optional nickname for the recipient. Useful for quick searches and display purposes.
Email address of a recipient, which may be used in case of an issue with a transaction.
Recipient's phone number.
Recipient's mobile number.
A Reference Id that you can assign to this recipient, for your records.
Optional payment reference required by some accounts. This reference should be used for future payments. It should not contain any special character.
Recipient added successfully

Organisational type of a recipient; whether an Individual or Corporate.

Three-letter ISO 3166-1 alpha-3 country code representing the recipient’s country.

Container for confirmation of recipient details.

This object is required only when the initial API call fails due to a Confirmation of Payee (CoP) check failure.

If the failure is related to CoP, the API response will include request_identifier and event_id, which must be used in the subsequent retry request along with the appropriate customer_action.