Create Extended Beneficiary

Create a beneficiary that includes all compliance related data for payouts.

The response provides a unique beneficiary ID, which you can use in place of the beneficiary object for Create Payout

This method triggers the Beneficiary Created Webhook webhook. This webhook contains the same information as the response.

Note

In addition to the required fields documented below, you must include all other fields listed for the beneficiary in the response to Get Payout Required Fields, and you must conform to the regex provided.

To create an extended beneficiary that you can use with multiple payout methods, include all fields that are required by each payout method. The client is responsible for including all required fields.

Parameters

Request Header Parameters

Request Body Parameters

- address
- Beneficiary's street address including the build number. For example: 123 East 32nd street.
- city
- City of the beneficiary.
- category
- The category of payout method type. One of the following:
  - bank
  - card
  - cash
  - ewallet - local eWallet (non-Rapyd)
  - rapyd_ewallet - Rapyd wallet. Must match the category of the payout method.
- company_name
- Name of the beneficiary company. Required when entity_type is company.
- country
- Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. The two-letter prefix of the payout method type must match the beneficiary country code.
- country_of_incorporation
- The country where the company was registered. Two-letter ISO 3166-1 ALPHA-2 code. Required when entity_type is company.
- currency
- Currency received by the beneficiary. Three-letter ISO 4217 code.
- date_of_birth
- Date of birth of the individual. Format: DD/MM/YYYY. Required when entity_type is individual.
- date_of_incorporation
- The date when the company was registered. Format: DD/MM/YYYY. Required when entity_type is company.
- default_payout_method_type
- The type of payout method for the beneficiary. The two-letter prefix must match the beneficiary country code.
- entity_type
- Type of entity for the beneficiary. One of the following values:
  - company
  - individual
- first_name
- First name of the beneficiary. Required when entity_type is individual.
- gender
- Gender of the individual. Required when entity_type is individual. One of the following values:
  - male
  - female
  - other
  - not_applicable
- identification_type
- Type of identification document for the beneficiary. When entity_type is company, this field must be company_registered_number. When entity_type is individual, one of the following values:
  - company_registered_number
  - drivers_license
  - identification_id
  - international_passport
  - residence_permit
  - social_security
  - work_permit
- identification_value
- Identification number on the document mentioned in identification_type.
- last_name
- Last name of the beneficiary. Required when entity_type is individual.
- merchant_reference_id
- Identifier defined by the client for reference purposes. Limit: 45 characters.
- nationality
- The citizenship of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code for the country. To determine the code for a country, see List Countries. Required when entity_type is individual.

Response Parameters

- address
- Beneficiary's street address including the build number. For example: 123 East 32nd street.
- amount
- Maximum payout amount to validate, in units of the currency defined in sender_currency. Decimal.
- beneficiary
- ID of the beneficiary object. String starting with beneficiary_.
- category
- The category of payout method type. One of the following:
  - bank
  - card
  - cash
  - ewallet - local eWallet (non-Rapyd)
  - rapyd_ewallet - Rapyd wallet. Must match the category of the payout method.
- city
- City of the beneficiary.
- company_name
- Name of the beneficiary company. Relevant when entity_type is company.
- confirmation_required
- Indicates whether the beneficiary must respond to accept or decline a payout. Relevant to the rapyd_ewallet payout method type.
  false
- country
- Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. The two-letter prefix of the payout method type must match the beneficiary country code.
- currency
- Currency received by the beneficiary. Three-letter ISO 4217 code.
- date_of_birth
- Date of birth of the individual. Format: DD/MM/YYYY. Relevant when entity_type is individual.
- date_of_incorporation
- The date when the company was registered. Format: DD/MM/YYYY. Relevant when entity_type is company.
- default_payout_method_type
- The type of payout method for the beneficiary. The two-letter prefix must match the beneficiary country code.
- entity_type
- Type of entity. One of the following values:
  - company
  - individual
- ewallet
- ID of the wallet that the money is transferred to. String starting with ewallet_. Relevant to payout to Rapyd Wallet.
- first_name
- First name of the beneficiary. Relevant when entity_type is individual.
- gender
- Gender of the individual. One of the following values:
  - male
  - female
  - other
  - not_applicable
- id
- ID of the 'beneficiary' object. String starting with beneficiary_.
- identification_type
- Type of identification document for the beneficiary. When entity_type is company, this field must be company_registered_number. When entity_type is individual, one of the following values:
  - drivers_license
  - identification_id
  - international_passport
  - residence_permit
  - social_security
  - work_permit
- identification_value
- Identification number on the document mentioned in identification_type.
- last_name
- Last name of the beneficiary. Relevant when entity_type is individual.
- merchant_reference_id
- Identifier defined by the client for reference purposes. Limit: 45 characters.
- nationality
- The citizenship of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code for the country. Relevant when entity_type is individual.
- validated
- Indicates whether the format of payout beneficiary details is valid for the payout method type.

/v1/payouts/extended_beneficiary

Create Extended Beneficiary - individual

curl -X post
https://sandboxapi.rapyd.net/v1/payouts/extended_beneficiary
-H 'access_key: your-access-key-here'
-H 'Content-Type: application/json'
-H 'idempotency: your-idempotency-parameter-here'
-H 'salt: your-random-string-here'
-H 'signature: your-calculated-signature-here'
-H 'timestamp: your-unix-timestamp-here'
-d '
{
    "category": "bank",
    "country": "CA",
    "currency": "USD",
    "entity_type": "individual",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "12/12/1999",
    "nationality": "CA",
    "gender": "male",
    "identification_type": "identification_id",
    "identification_value": "123456789",
    "default_payout_method_type": "ca_general_bank",
    "merchant_reference_id": "JohnDoe",
    "payment_type": "priority",
    "address": "1 Main Street",
    "city": "Montreal",
    "state": "Quebec",
    "postcode": "12345",
    "account_number": "1234567"
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "7025e088-3bf0-4fd7-a56c-0a4faf096964"
    },
    "data": {
        "id": "beneficiary_a112a2437974c11c26f69f1d079d142b",
        "last_name": "Doe",
        "first_name": "John",
        "country": "CA",
        "entity_type": "individual",
        "address": "1 Main Street",
        "name": "John Doe",
        "date_of_birth": "12/12/1999",
        "postcode": "12345",
        "city": "Montreal",
        "state": "Quebec",
        "account_number": "1234567",
        "currency": "USD",
        "identification_type": "identification_id",
        "identification_value": "*********",
        "nationality": "CA",
        "merchant_reference_id": "JohnDoe",
        "gender": "male",
        "payment_type": "priority",
        "category": "bank",
        "default_payout_method_type": "ca_general_bank"
    }
}

Create Extended Beneficiary - company

curl -X post
https://sandboxapi.rapyd.net/v1/payouts/extended_beneficiary
-H 'access_key: your-access-key-here'
-H 'Content-Type: application/json'
-H 'idempotency: your-idempotency-parameter-here'
-H 'salt: your-random-string-here'
-H 'signature: your-calculated-signature-here'
-H 'timestamp: your-unix-timestamp-here'
-d '
{
    "category": "bank",
    "company_name": "All Star Limousine",
    "date_of_incorporation": "11/11/1995",
    "country_of_incorporation": "US",
    "address": "425 12th avenue",
    "city": "anytown",
    "country": "US",
    "currency": "USD",
    "entity_type": "company",
    "identification_type": "company_registered_number",
    "identification_value": "9876543210",
    "merchant_reference_id": "AllStarLimo",
    "account_number": "0987654321",
    "aba": "987654321"
}
'

 {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "1e26e11e-5d39-4295-b9fb-c9b59f35201b"
    },
    "data": {
        "id": "beneficiary_71c0cf8bc8670f942b78d18f85e825e2",
        "country": "US",
        "entity_type": "company",
        "address": "425 12th avenue",
        "name": "All Star Limousine",
        "date_of_incorporation": "11/11/1995",
        "city": "anytown",
        "company_name": "All Star Limousine",
        "account_number": "0987654321",
        "currency": "USD",
        "identification_type": "company_registered_number",
        "identification_value": "**********",
        "merchant_reference_id": "AllStarLimo",
        "country_of_incorporation": "US",
        "aba": "987654321",
        "category": "bank"
    }
}

In this section:

Documentation