--- title: "Create Beneficiary Tokenization Page" source_url: https://docs.rapyd.net/en/create-beneficiary-tokenization-page.html lang: en --- # Create Beneficiary Tokenization Page Create a customer-facing page for creating a beneficiary token. This method creates a URL for a page where the customer enters details required for payouts to the beneficiary’s bank account. All available payout methods for the beneficiary’s country are listed. > **Note:** > > - If `beneficiary_country` is not specified, the customer specifies the country on the beneficiary tokenization page. As a best practice, Rapyd recommends always filling this field in and not leaving it to the customer. > - For an individual beneficiary, if `first_name` and `last_name` are not specified, the customer provides this information on the beneficiary tokenization page. > - When the customer provides all required information, a beneficiary object is created and Rapyd sends a webhook to the client with the ID of the beneficiary object. ### 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 - - beneficiary_country - The two-letter ISO 3166-1 ALPHA-2 code for the country of the beneficiary’s bank account. The two-letter prefix of the payout method type matches the beneficiary country code. - - beneficiary_entity_type - Type of entity for the beneficiary. One of the following: - **company** - **individual** - - beneficiary_extended_fields - When the value is **true**, the hosted tokenization page displays additional required fields. - Additional required fields when `beneficiary_entity_type` is **individual**: `address`, `city`, `country`, `date_of_birth`, `first_name`, `gender`, `identification_type`, `identification_value`, `last_name`, `nationality`. - Additional required fields when `beneficiary_entity_type` is **company**: `address`, `city`, `company_name`, `country`, `country_of_incorporation`, `date_of_incorporation`, `identification_type`, `identification_value`. For more information on the additional required fields, see [Create Extended Beneficiary](https://docs.rapyd.net/en/create-extended-beneficiary.md "Create Extended Beneficiary"). false > **Note:** > > Currently only available in the sandbox. - - beneficiary_optional_fields - Additional information about the beneficiary. - - company_name - The name of the beneficiary's company. Relevant to beneficiaries that are not individuals. If the request does not contain this information, the hosted page prompts the customer for it. > **Note:** > > If `beneficiary_entity_type` is **individual**, this field must be omitted. - - first_name - The first name of the beneficiary. Relevant to individual beneficiaries. If the request does not contain this information, the redirect page prompts the customer for it. - - identification_type - Type of identification document. 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 - The identification of the document mentioned in `identification_type`. - - last_name - The last name of the beneficiary. Relevant to individual beneficiaries. If the request does not contain this information, the redirect page prompts the customer for it. - - cancel_url - URL where the customer is redirected after pressing **Back to Website** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs. - - category - The category of payout method. One of the following: - **bank** - **card** - - complete_url - URL where the customer is redirected after pressing **Close** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs. - - language - Determines the default language of the hosted page. For a list of values, see [List Supported Languages](https://docs.rapyd.net/en/list-supported-languages.md "List Supported Languages"). - When this parameter is null, the language of the user's browser is used. - If the language of the user's browser cannot be determined, the default language is English. - - merchant_alias - Client's name. Rapyd - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - - page_expiration - End of the time when the customer can use the hosted page, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). If `page_expiration` is not set, the hosted page expires 14 days after creation. **Range:** 1 minute to 30 days. - - payout_currency - Currency accepted by the beneficiary’s bank account. Three-letter ISO 4217 code. - - payout_method_types_exclude - List of payout methods that are excluded from display on the beneficiary tokenization page. - - payout_method_types_include - Array of strings. List of payout methods that are displayed on the beneficiary tokenization page. - - sender_country - The two-letter ISO 3166-1 ALPHA-2 code for the sender’s country. - - sender_currency - Currency paid from the sender’s wallet. Three-letter ISO 4217 code. - - sender_entity_type - Type of entity for the sender. One of the following: - **company** - **individual** ### Response Parameters - - beneficiary_country - The two-letter ISO 3166-1 ALPHA-2 code for the country of the beneficiary’s bank account. The two-letter prefix of the payout method type must match the beneficiary country code. - - beneficiary_currency - Currency accepted by the beneficiary’s bank account. Three-letter ISO 4217 code. - - beneficiary_entity_type - Type of entity for the beneficiary. One of the following: - **company** - **individual** - - beneficiary_extended_fields - When the value is **true**, the hosted tokenization page displays additional required fields. - Additional required fields when `beneficiary_entity_type` is **individual**: `address`, `city`, `country`, `date_of_birth`, `first_name`, `gender`, `identification_type`, `identification_value`, `last_name`, `nationality`. - Additional required fields when `beneficiary_entity_type` is **company**: `address`, `city`, `company_name`, `country`, `country_of_incorporation`, `date_of_incorporation`, `identification_type`, `identification_value`. For more information on the additional required fields, see [Create Extended Beneficiary](https://docs.rapyd.net/en/create-extended-beneficiary.md "Create Extended Beneficiary"). - - beneficiary_id - ID of the beneficiary. String starting with **beneficiary_**. - - beneficiary_optional_fields - Additional information about the beneficiary. - - company_name - The name of the beneficiary's company. Relevant to **company** beneficiaries. - - first_name - The first name of the beneficiary. Relevant to **individual** beneficiaries. - - identification_type - Type of identification document. When `entity_type` is **company**, this field is **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 - The identification number of the document mentioned in `identification_type`. - - last_name - The last name of the beneficiary. Relevant to individual beneficiaries. - - beneficiary_validated - Indicates whether the beneficiary has been validated. See [Validate Beneficiary](https://docs.rapyd.net/en/validate-beneficiary.md "Validate Beneficiary"). - - cancel_url - URL where the customer is redirected after pressing **Back to Website** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs. - - category - The category of payout method. One of the following: - **bank** - **card** - US only. - - complete_url - URL where the customer is redirected after pressing **Close** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs. - - country - The two-letter ISO 3166-1 ALPHA-2 code for the beneficiary’s country. The two-letter prefix of the payout method type must match the beneficiary country code. - - currency - Currency accepted by the beneficiary’s bank account. Three-letter ISO 4217 code. - - entity_type - Type of entity for the beneficiary. One of the following: - **company** - **individual** - - expiration - The page expiration date in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - id - ID of the beneficiary tokenization page. String starting with **hp_ben_**. - - language - Determines the default language of the hosted page. For a list of values, see [List Supported Languages](https://docs.rapyd.net/en/list-supported-languages.md "List Supported Languages"). - When this parameter is null, the language of the user's browser is used. - If the language of the user's browser cannot be determined, the default language is English. - - merchant_alias - Client's name. Rapyd - - merchant_color - Color of the call-to-action (CTA) button on the hosted page. To configure this field, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page"). - - merchant_customer_support - Contains details of the client’s customer support. To configure these fields, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page"). - - email - Email address. - - url - URL for the client's customer support service. - - phone_number - Phone number for contacting the client's customer support service. - - merchant_logo - URL for the image of the client's logo. To configure this field, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page"). - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - - merchant_website - The URL where the customer is redirected after exiting the hosted page. Relevant when one or both of the following fields is unset: - `cancel_url` - `complete_url` To configure this field, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page"). - - page_expiration - End of the time when the customer can use the hosted page, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). If `page_expiration` is not set, the hosted page expires 14 days after creation. **Range:** 1 minute to 30 days. - - payout_currency - Currency accepted by the beneficiary’s bank account. Three-letter ISO 4217 code. - - payout_method_type - The payout method type selected by the customer. The two-letter prefix must match the beneficiary country code. - - payout_method_types_exclude - List of payout methods that are excluded from display on the beneficiary tokenization page. Array of strings. - - payout_method_types_include - List of payout methods that are displayed on the beneficiary tokenization page. Array of strings. - - redirect_url - URL of the hosted page that is shown to the customer. - - sender_country - The two-letter ISO 3166-1 ALPHA-2 code for the sender’s country. - - sender_currency - Currency paid from the sender’s wallet. Three-letter ISO 4217 code. - - sender_entity_type - Type of entity for the sender. One of the following: - **company** - **individual** - - status - Status of the hosted page. One of the following: - **NEW** - The hosted page was created. - **DON** - Done. The beneficiary details were saved. - **EXP** - The hosted page expired. - - timestamp - Timestamp for the request to create the beneficiary tokenization object page, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - tokenization_page - ID of the beneficiary tokenization page. String starting with **hp_ben_**. ### Code Samples - - .NET - ```csharp using System; using System.Text.Json; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { var requestObj = new { category = "bank", beneficiary_entity_type = "individual", merchant_reference_id = "b-100456", cancel_url = "http://example.com/cancel", complete_url = "http://example.com/complete", sender_country = "US", beneficiary_optional_fields = new { identification_type = "international_passport", identification_value = "123456789" }, string payout_method_types_exclude = new string[] { "us_bank" }; sender_currency = "USD", payout_currency = "EUR", sender_entity_type = "company" }; string request = JsonSerializer.Serialize(requestObj); string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/hosted/disburse/beneficiary", request); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ```javascript const makeRequest = require('/utilities').makeRequest; async function main() { try { const body = { category: 'bank', beneficiary_entity_type: 'individual', merchant_reference_id: 'b-100456', cancel_url: 'http://example.com/cancel', complete_url: 'http://example.com/complete', sender_country: 'US', beneficiary_optional_fields: { identification_type: 'international_passport', identification_value: '123456789' }, payout_method_types_exclude: ['us_bank'], sender_currency: 'USD', payout_currency: 'EUR', sender_entity_type: 'company' }; const result = await makeRequest('POST', '/v1/hosted/disburse/beneficiary', body); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); $body = [ "category" => "bank", "beneficiary_entity_type" => "individual", "merchant_reference_id" => "b-100456", "cancel_url" => "http://example.com/cancel", "complete_url" => "http://example.com/complete", "sender_country" => "US", "beneficiary_optional_fields" => array( "identification_type" => "international_passport", "identification_value" => "123456789" ), "payout_method_types_exclude" => [ "us_bank" ], "sender_currency" => "USD", "payout_currency" => "EUR", "sender_entity_type" => "company" ]; try { $object = make_request('post', '/v1/hosted/disburse/beneficiary', $body); var_dump($object); } catch(Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request request_body = { "category": "bank", "beneficiary_entity_type": "individual", "merchant_reference_id": "b-100456", "cancel_url": "http://example.com/cancel", "complete_url": "http://example.com/complete", "sender_country": "US", "beneficiary_optional_fields": { "identification_type": "international_passport", "identification_value": "123456789" }, "payout_method_types_exclude": [ "us_bank" ], "sender_currency": "USD", "payout_currency": "EUR", "sender_entity_type": "company" } results = make_request(method='post', path='/v1/hosted/disburse/beneficiary', body=request_body) pprint(results) ``` - /v1/hosted/disburse/beneficiary - Category=Bank, Beneficiary=Individual - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/disburse/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", "beneficiary_entity_type": "individual", "merchant_reference_id": "2025-11-06a", "cancel_url": "http://cancel.rapyd.net", "complete_url": "http://complete.rapyd.net", "sender_country": "US", "beneficiary_optional_fields": { "identification_type": "international_passport", "identification_value": "123456789" }, "sender_currency": "USD", "payout_currency": "EUR", "sender_entity_type": "company" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "84b76693-0610-47c6-a342-f25745546e98" }, "data": { "status": "NEW", "cancel_url": "http://cancel.rapyd.net", "complete_url": "http://complete.rapyd.net", "language": null, "merchant_color": "323fff", "merchant_logo": null, "merchant_website": "https://example1234.net", "merchant_customer_support": { "url": "https://example1234.net", "email": "support@example1234.net", "phone_number": "121255551213" }, "merchant_alias": "Doc Team", "page_expiration": 1763636567, "redirect_url": "https://sandboxhosted.rapyd.net/disburse/beneficiary?token=hp_ben_177ebbfca0ed39944190d1b8abe9a33a", "id": "hp_ben_177ebbfca0ed39944190d1b8abe9a33a", "category": "bank", "sender_entity_type": "company", "sender_country": "US", "merchant_reference_id": "2025-11-06a", "beneficiary_entity_type": "individual", "beneficiary_country": null, "beneficiary_currency": "EUR", "sender_currency": "USD", "beneficiary_id": null, "payout_method_type": null, "beneficiary_validated": false, "timestamp": 1762426969, "beneficiary_optional_fields": { "last_name": null, "first_name": null, "company_name": null, "identification_type": "international_passport", "identification_value": "123456789" }, "payout_method_types_include": null, "payout_method_types_exclude": null, "expiration": 1763636567, "beneficiary_extended_fields": false } } ``` - Category=Bank, Beneficiary=Company - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/disburse/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", "beneficiary_entity_type": "company", "merchant_reference_id": "bank_company", "cancel_url": "http://cancel.rapyd.net", "complete_url": "http://complete.rapyd.net", "sender_country": "SG", "beneficiary_country": "DE", "beneficiary_optional_fields": { "last_name": "", "first_name": "", "company_name": "Four Star Limousine Service", "identification_type": "company_registered_number", "identification_value": "123456789" }, "sender_entity_type": "company" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "34832027-3188-4e9b-a7e3-5cfd8ca87326" }, "data": { "status": "NEW", "cancel_url": "http://cancel.rapyd.net", "complete_url": "http://complete.rapyd.net", "language": null, "merchant_color": "323fff", "merchant_logo": null, "merchant_website": "https://example1234.net", "merchant_customer_support": { "url": "https://example1234.net", "email": "support@example1234.net", "phone_number": "121255551213" }, "merchant_alias": "Doc Team", "page_expiration": 1763637661, "redirect_url": "https://sandboxhosted.rapyd.net/disburse/beneficiary?token=hp_ben_14df7bb862198a9c401228234da69033", "id": "hp_ben_14df7bb862198a9c401228234da69033", "category": "bank", "sender_entity_type": "company", "sender_country": "SG", "merchant_reference_id": "bank_company", "beneficiary_entity_type": "company", "beneficiary_country": "DE", "beneficiary_currency": "EUR", "sender_currency": "SGD", "beneficiary_id": null, "payout_method_type": null, "beneficiary_validated": false, "timestamp": 1762428063, "beneficiary_optional_fields": { "last_name": null, "first_name": null, "company_name": "Four Star Limousine Service", "identification_type": "company_registered_number", "identification_value": "123456789" }, "payout_method_types_include": null, "payout_method_types_exclude": null, "expiration": 1763637661, "beneficiary_extended_fields": false } } ``` - Category=Card, Beneficiary=Individual - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/disburse/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": "card", "beneficiary_entity_type": "individual", "merchant_reference_id": "johndoe", "cancel_url": "http://example.com/cancel", "complete_url": "http://example.com/complete", "sender_country": "US", "beneficiary_optional_fields": { "first_name": "John", "last_name": "Doe", "identification_type": "international_passport", "identification_value": "123456789" }, "sender_currency": "USD", "payout_currency": "USD", "sender_entity_type": "company" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "844c5b93-851a-4e6c-bade-f0989f391016" }, "data": { "status": "NEW", "cancel_url": "http://example.com/cancel", "complete_url": "http://example.com/complete", "language": null, "merchant_color": "323fff", "merchant_logo": null, "merchant_website": "https://example1234.net", "merchant_customer_support": { "url": "https://example1234.net", "email": "support@example1234.net", "phone_number": "121255551213" }, "merchant_alias": "Doc Team", "page_expiration": 1763637744, "redirect_url": "https://sandboxhosted.rapyd.net/disburse/beneficiary?token=hp_ben_c8a409ec2e711b7f618e33eec03e729f", "id": "hp_ben_c8a409ec2e711b7f618e33eec03e729f", "category": "card", "sender_entity_type": "company", "sender_country": "US", "merchant_reference_id": "johndoe", "beneficiary_entity_type": "individual", "beneficiary_country": null, "beneficiary_currency": "USD", "sender_currency": "USD", "beneficiary_id": null, "payout_method_type": null, "beneficiary_validated": false, "timestamp": 1762428146, "beneficiary_optional_fields": { "last_name": "Doe", "first_name": "John", "company_name": null, "identification_type": "international_passport", "identification_value": "123456789" }, "payout_method_types_include": null, "payout_method_types_exclude": null, "expiration": 1763637744, "beneficiary_extended_fields": false } } ``` - Bad Request - ID Type Misspelled - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/disburse/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", "beneficiary_entity_type": "individual", "merchant_reference_id": "2025-12-18a", "cancel_url": "http://cancel.rapyd.net", "complete_url": "http://complete.rapyd.net", "sender_country": "US", "beneficiary_optional_fields": { "identification_type": "drivers_licence", "identification_value": "123456789" }, "sender_currency": "USD", "payout_currency": "EUR", "sender_entity_type": "company" }' ``` - ```json { "status": { "error_code": "ERROR_HOSTED_PAGE_BENEFICIARY_INVALID_IDENTIFICATION_TYPE", "status": "ERROR", "message": "The request attempted to create a beneficiary with a hosted page, but the ID type was not valid. The request was rejected. Corrective action: In the 'beneficiary_optional_fields' object, set a valid value for 'identification_type'. For details, see the API reference.", "response_code": "ERROR_HOSTED_PAGE_BENEFICIARY_INVALID_IDENTIFICATION_TYPE", "operation_id": "2aa955e6-5664-4bd9-8c29-8eb817843a1d" } } ``` - Bad Request - Category Not Supported - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/disburse/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": "ewallet", "beneficiary_entity_type": "individual", "merchant_reference_id": "2025-12-18b", "cancel_url": "http://cancel.rapyd.net", "complete_url": "http://complete.rapyd.net", "sender_country": "US", "beneficiary_optional_fields": { "identification_type": "drivers_license", "identification_value": "123456789" }, "sender_currency": "USD", "payout_currency": "EUR", "sender_entity_type": "company" }' ``` - ```json { "status": { "error_code": "ERROR_HOSTED_PAGE_NO_SUPPORTED_PAYOUT_METHOD_TYPES", "status": "ERROR", "message": "The request attempted a hosted page operation, but there are no supported payout method types for the combination of the attributes that has been specified. The request was rejected. Corrective action: Run 'List Payout Method Types'. Use only supported countries and entity types, and use only currencies that are supported for each country.", "response_code": "ERROR_HOSTED_PAGE_NO_SUPPORTED_PAYOUT_METHOD_TYPES", "operation_id": "9e35dda7-aded-410e-b298-bef13f67996d" } } ``` ### Related Information - [Beneficiary Account Details](https://docs.rapyd.net/en/hosted-beneficiary-details-page.md "Hosted Beneficiary Details Page")