--- title: "Create Extended Beneficiary" source_url: https://docs.rapyd.net/en/create-extended-beneficiary.html lang: en --- # 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](https://docs.rapyd.net/en/create-payout.md "Create Payout") This method triggers the [Beneficiary Created Webhook](https://docs.rapyd.net/en/beneficiary-created-webhook.md "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](https://docs.rapyd.net/en/get-payout-required-fields.md "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. > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: > > - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - [Payout Errors](https://docs.rapyd.net/en/payout-errors.md "Payout Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). ### Parameters ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Request Body Parameters - - address - Beneficiary's street address including the building 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** - **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. - - currency - Currency received by the beneficiary. Three-letter ISO 4217 code. > **Note:** > > Four-letter codes are supported for stablecoin (USDC). - - country_of_incorporation - The country where the company was registered. Two-letter ISO 3166-1 ALPHA-2 code. Required when `entity_type` is **company**. - - 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. The prefix **xx_** matches all countries. - - 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: - **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. Required when `entity_type` is **individual**. To determine the code for a country, see [List Countries](https://docs.rapyd.net/en/list-countries.md "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`. 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. > **Note:** > > Four-letter codes are supported for stablecoin (USDC). - - 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. Two-letter ISO 3166-1 ALPHA-2 code for the country. Relevant when `entity_type` is **individual**. - /v1/payouts/extended_beneficiary - Create Extended Beneficiary - Individual - ```curl 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' \ --data-raw '{ "category": "bank", "country": "US", "currency": "USD", "entity_type": "individual", "first_name": "John", "last_name": "Doe", "date_of_birth": "12/12/1999", "nationality": "US", "gender": "male", "identification_type": "identification_id", "identification_value": "123456789", "default_payout_method_type": "us_general_bank", "merchant_reference_id": "JohnDoe", "payment_type": "priority", "address": "1 Main Street", "city": "NewTown", "state": "New State", "postcode": "12345", "account_number": "1234567" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "013d9492-dc77-4f6f-8dc8-f30424e27f41" }, "data": { "id": "beneficiary_210dac4f3b5d9843dfb381d5846fbed8", "last_name": "Doe", "first_name": "John", "country": "US", "entity_type": "individual", "address": "1 Main Street", "name": "John Doe", "date_of_birth": "12/12/1999", "postcode": "12345", "city": "NewTown", "state": "New State", "account_number": "1234567", "currency": "USD", "identification_type": "identification_id", "identification_value": "*********", "nationality": "US", "merchant_reference_id": "JohnDoe", "gender": "male", "payment_type": "priority", "category": "bank", "default_payout_method_type": "us_general_bank" } } ``` - Create Extended Beneficiary - Company - ```curl 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' \ --data-raw '{ "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" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "9849242a-fc10-4fec-8dc8-b8e2fff31c0a" }, "data": { "id": "beneficiary_bbfe53c25eb3f56cf2cabdcbcd2017ee", "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" } } ``` - Bad Request - Invalid Extended Beneficiary Field - ID Type (Individual) - ```curl 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' \ --data-raw '{ "category": "bank", "country": "US", "currency": "USD", "entity_type": "individual", "first_name": "John", "last_name": "Doe", "date_of_birth": "12/12/1999", "nationality": "US", "gender": "male", "identification_type": "employment_permit", "identification_value": "123456789", "default_payout_method_type": "us_general_bank", "merchant_reference_id": "JohnDoe", "payment_type": "priority", "address": "1 Main Street", "city": "NewTown", "state": "New State", "postcode": "12345", "account_number": "1234567" }' ``` - ```json { "status": { "error_code": "INVALID_REQUIRED_FIELD - [IDENTIFICATION_TYPE]", "status": "ERROR", "message": "The request attempted a payout operation, but the value of one of the fields was not valid. The request was rejected. Corrective action: The name of the problematic field appears at the end of the error code. Provide a value that matches the regex defined in the response to 'Get Payout Required Fields'.", "response_code": "INVALID_REQUIRED_FIELD - [IDENTIFICATION_TYPE]", "operation_id": "ee34f230-6c8d-4c13-bf90-c2fe493024d6" } } ``` - Bad Request - Missing Input Fields (Individual) - ```curl 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' \ --data-raw '{ "category": "bank", "country": "US", "currency": "USD", "entity_type": "individual", "first_name": "John", "last_name": "Doe", "date_of_birth": "12/12/1999", "nationality": "US", "gender": "male", "identification_type": "identification_id", "identification_value": "", "default_payout_method_type": "us_general_bank", "merchant_reference_id": "JohnDoe", "payment_type": "priority", "address": "1 Main Street", "city": "NewTown", "state": "New State", "postcode": "12345", "account_number": "1234567" }' ``` - ```json { "status": { "error_code": "MISSING_FIELDS - [BENEFICIARY.IDENTIFICATION_VALUE]", "status": "ERROR", "message": "The request attempted an operation, but one or more required fields were missing. The request was rejected. Corrective action: Provide all of the fields that are listed at the end of the error code. For more information, see the API Reference.", "response_code": "MISSING_FIELDS - [BENEFICIARY.IDENTIFICATION_VALUE]", "operation_id": "01c90ee8-14fc-4f81-adb3-65155dc2efb1" } } ```