Add a new recipient | Redpin

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.

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.

Authentication

AuthorizationBearer

OAuth 2.0 Bearer token authentication. This API uses OAuth 2.0 Client Credentials flow. Please refer to the Authentication section for detailed information on how to obtain and use your OAuth credentials.

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 country code representing the recipient’s country.

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:

IBAN:

1 {"currency": "AED", "iban": "AE070331234567890123456"}

Account number and Swift code:

1 {"currency": "AED", "account_number": "12345678", "swift_code": "BOMLAEADXXX"}

Account number, Swift code, and Routing code value:

1 {"currency": "AED", "account_number": "12345678", "swift_code": "BOMLAEADXXX", "routing_code_value": "601613"}

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

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) or Verification of Payee (VoP) check failure.

If the failure is related to CoP/VoP, 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.

Detailed instructions for handling these scenarios can be found in:

Container for confirmation of recipient details. This object is required only when the initial API call fails due to a [Confirmation of Payee (CoP)](https://www.wearepay.uk/what-we-do/overlay-services/confirmation-of-payee/) or [Verification of Payee (VoP)](https://www.europeanpaymentscouncil.eu/what-we-do/other-schemes/verification-payee) check failure. If the failure is related to CoP/VoP, 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`. Detailed instructions for handling these scenarios can be found in: - [UK Confirmation of Payee (CoP) Guide](/api-guide/regulatory-guides/cop-guide) - [SEPA Verification of Payee (VoP) Guide](/api-guide/regulatory-guides/vop-guide)

additional_detailsobjectOptional

Additional details for the recipient.

Response

Recipient added successfully or CoP/VoP verification failure

client_reference_idstring or null

Reference Id assigned to this recipient. Present in successful responses.

recipient_idstring or null

Unique identifier for the recipient. Present in successful responses.

codestring or null

Response code from the CoP/VoP check. Indicates the type of match result from the payee’s bank. Present only when CoP/VoP verification fails.

descriptionstring or null

Human-readable description of the CoP/VoP check result. Present only when CoP/VoP verification fails.

recipient_checkobject or null

Details of the CoP/VoP check result including identifiers needed for retry. Present only when CoP/VoP verification fails.

Errors