Update Beneficiary

Update a beneficiary with additional fields.

Note

You cannot update the values of the beneficiary fields which were defined when it was created.
The code samples include successful requests (200) and bad requests (400).
- For error messages that appear due to bad requests (400), see:
  - General Errors
  - Payout Errors
- For information about unauthorized request (401) and other authentication errors, see Troubleshooting Authentication and Authorization Errors.

Parameters

Request Header Parameters

Request Path Parameters

beneficiary
ID of the beneficiary object. String starting with beneficiary_.

Request Body Parameters

Note

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

- address
- Beneficiary's street address including the building number. For example: 123 East 32nd street.
- city
- City of the beneficiary.
- company_name
- Name of the beneficiary company. Relevant 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. Relevant when entity_type is company.
- 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. The prefix xx_ matches all countries.
- first_name
- First name of the beneficiary. Relevant when entity_type is individual.
- gender
- Gender of the individual. Relevant 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. 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. To determine the code for a country, see List Countries.

Response Parameters

- address
- Beneficiary's street address including the building number. For example: 123 East 32nd street.
- amount
- Maximum payout amount to validate, in units of the currency defined in sender_currency.
- 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.
- 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. Relevant when entity_type is 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. Relevant when entity_type is individual.

/v1/payouts/beneficiary/:beneficiary

Update Beneficiary - Individual

curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/beneficiary_0e1c96eac00e22a6875b9ba5107a310a' \
-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' \
--data-raw '{
    "state": "Illinois",
    "postcode": "12345"
}'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "af4bd368-a5fa-4d79-a51d-9fcc344d8d74"
    },
    "data": {
        "id": "beneficiary_cb009f46c8dcd85004c8054541287723",
        "last_name": "Doe",
        "first_name": "John",
        "country": "US",
        "entity_type": "individual",
        "address": "1 Main Street",
        "name": "John Doe",
        "postcode": "12345",
        "city": "Anyyown",
        "state": "Illinois",
        "account_number": "1234567",
        "currency": "USD",
        "identification_type": "identification_id",
        "identification_value": "*********",
        "merchant_reference_id": "JohnDoe",
        "gender": "other",
        "bic_swift": "12345678XXX",
        "payment_type": "priority",
        "category": "bank",
        "default_payout_method_type": "us_general_bank"
    }
}

Bad Request - Update Beneficiary with No New Fields

curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/beneficiary_0e1c96eac00e22a6875b9ba5107a310a' \
-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' \
--data-raw '{
    "state": "Illinois",
    "postcode": "12345"
}'

{
    "status": {
        "error_code": "ERROR_UPDATE_BENEFICIARY_WITH_NO_NEW_FIELDS",
        "status": "ERROR",
        "message": "The request attempted to update a beneficiary field, but its value has already been defined. The request was rejected. Corrective action: Update only values of beneficiary fields that were not previously defined.",
        "response_code": "ERROR_UPDATE_BENEFICIARY_WITH_NO_NEW_FIELDS",
        "operation_id": "51ce8647-5495-4f44-bc90-d6b22416693b"
    }
}

Bad Request - Beneficiary Not Found

curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/beneficiary0e1c96eac00e22a6875b9ba5107a310a' \
-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' \
--data-raw '{
    "state": "Illinois",
    "postcode": "12345"
}'

{
    "status": {
        "error_code": "ERROR_GET_BENEFICIARY",
        "status": "ERROR",
        "message": "The request attempted an operation that requires a payout beneficiary, but the beneficiary was not found. The request was rejected. Corrective action: Use the ID of a valid beneficiary.",
        "response_code": "ERROR_GET_BENEFICIARY",
        "operation_id": "b08b8ef7-56ef-43c6-b437-f53395b2ab83"
    }
}

In this section:

Documentation

Update Beneficiary

Note

Parameters

Request Header Parameters

Request Path Parameters

Request Body Parameters

Note

Response Parameters

Search results