--- title: "Hosted Beneficiary Details Page" source_url: https://docs.rapyd.net/en/hosted-beneficiary-details-page.html lang: en --- # Hosted Beneficiary Details Page Easily collect your beneficiary details for future payouts. | `Enterprise` Rapyd Disburse can be used to pay beneficiaries such as a contractor, workers, suppliers, or businesses anywhere in the world. The Hosted Beneficiary Details Page allows Rapyd to collect a [beneficiary's](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_beneficiary "Beneficiary") sensitive information through a secure web form for future payouts. To learn more about reusing beneficiary's information in future payouts, refer to [Reusing Beneficiary or Sender](https://docs.rapyd.net/en/reusing-beneficiary-or-sender.md "Reusing Beneficiary or Sender"). - You need to pay a contract worker, on a regular basis and you need an efficient way to securely collect and store their personal information. - You need to capture and safely store business account information so that you can easily send repeat payouts to your business supplier. ### Hosted Beneficiary Details Page Flow ![account-details.jpg](image/img-93676680dfbd52f5fec50829f32490be.jpg) 1. You request Rapyd to generate a single, or multiple [Hosted Beneficiary Details Pages](https://docs.rapyd.net/en/save-beneficiary-details.md "Save Beneficiary Details") for different beneficiaries. 2. Rapyd processes your request and sends a response with the [redirect URL](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_redirect "Redirect URL"). 3. You display the redirect URL to the customer. 4. The customer completes and submits their information on the hosted page. 5. Rapyd generates an ID for each beneficiary to reuse in the future. ### Beneficiary Tokenization Message Sequences The message sequence diagrams below describe how information is exchanged between Rapyd, the merchant, and the merchant's customers. Create Beneficiary Tokenization Page ![beneficiary-via-hosted-page.svg](image/img-1971ebb5a6a94a1774970646f8718c12.svg) ### Beneficiary Tokenization Page Statuses The finite state diagram below summarizes the statuses for the beneficiary tokenization page. ![hosted-page.svg](image/img-efb9993e7ebd08de9f197d3139fe0aba.svg) Description of Statuses | Status | Description | | --- | --- | | NEW | New - The beneficiary tokenization hosted page was created. | | DON | Done - The hosted page was completed. The beneficiary details were submitted. | | EXP | Expired - The beneficiary tokenization hosted page has expired. | ### How Beneficiary Accounts Work Beneficiary information is collected through a hosted page and is tokenized (stored in a digital asset form). Rapyd securely collects the data so you don't have to manually gather, store, and send sensitive information. In addition, you can generate multiple hosted pages sent to different beneficiaries by email to collect this information using the Rapyd Client Portal as described on the [Save Beneficiary Details](https://docs.rapyd.net/en/save-beneficiary-details.md "Save Beneficiary Details") page for the Client Portal Guide. - The hosted page supports the following payout methods: - Bank transfers - Cards ### Generate a Hosted Page You can create a hosted page with the [Create Beneficiary Tokenization Page](https://docs.rapyd.net/en/create-beneficiary-tokenization-page.md "Create Beneficiary Tokenization Page") API using POST method. > **Note:** > > `merchant_reference_id` is an identifier for the beneficiary that links to the merchant, which is returned in the API response. ### Generate Hosted Page Request The [Create Beneficiary Tokenization Page](https://docs.rapyd.net/en/create-beneficiary-tokenization-page.md "Create Beneficiary Tokenization Page") describes the parameters in the request. > **Note:** > > Use the `payout_currency` field to list what currencies the beneficiary can use for payouts. Pass the value `USDC` for the `payout_currency` field to use the beneficiary token for cryptocurrency transactions. - - Request - ``` { "category": "bank", "sender_entity_type": "company", "sender_country": "US", "merchant_reference_id": "A-1013", "beneficiary_country": "US", "beneficiary_entity_type": "company", "beneficiary_optional_fields": { "last_name": null, "first_name": null, "company_name": "TestBeneficiaryCompany", "identification_type": "company_registered_number", "identification_value": "123456789" } } ``` > **Note:** > > The `beneficiary_optional_fields` object is optional to create a hosted page but is required once you create a beneficiary. Refer to the **beneficiary_optional_fields** in the [Create Beneficiary Tokenization Page](https://docs.rapyd.net/en/create-beneficiary-tokenization-page.md "Create Beneficiary Tokenization Page") for more details. - If these fields are passed in the request, then the beneficiary will not need to fill them in again. - If these fields are not passed in the request, then the beneficiary will be required to fill them in on the hosted page. > **Note:** > > Creating an extended beneficiary allows a merchant to collect additional information about their beneficiary before creating a payout. A beneficiary token ID is created, and is then passed in the [Create Payout](https://docs.rapyd.net/en/create-payout.md "Create Payout") request. > > If the value for `beneficiary _extended_fields` is set to `true`, then the Hosted Beneficiary Details page will have additional fields to gather the information about the extended beneficiary. > > For example, you could use an extended beneficiary for a payout if you are: > > - Making disbursements to independent content creators > - Creating payouts for entertainment-based business platforms > - Making a local payout to a supplier > > See [Create Extended Beneficiary](https://docs.rapyd.net/en/create-extended-beneficiary.md "Create Extended Beneficiary") for more information. ### Generate Hosted Page Response The following response lists the `redirect_url` to display the Hosted Beneficiary Account Details Page for the end user to enter in sensitive information (card number, bank account number, etc.). [Create Beneficiary Tokenization Page](https://docs.rapyd.net/en/create-beneficiary-tokenization-page.md "Create Beneficiary Tokenization Page") that describes the fields in the response. - - Response - ``` { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "bb178b63-7134-40c9-9818-b04950f541ac" }, "data": { "id": "hp_ben_d0e257f33e5ef13956ac6037ccb36909", "status": "NEW", "category": "bank", "sender_entity_type": "company", "sender_country": "US", "merchant_reference_id": "A-1013", "beneficiary_entity_type": "company", "beneficiary_country": "US", "beneficiary_currency": "USD", "sender_currency": "USD", "beneficiary_id": null, "payout_method_type": null, "beneficiary_validated": false, "redirect_url": "https://sandboxhosted.rapyd.net/disburse/beneficiary?token=hp_ben_d0e257f33e5ef13956ac6037ccb36909", "merchant_customer_support": { "email": null, "url": null, "phone_number": null }, "expiration": 1614196794, "timestamp": 1612987194, "beneficiary_optional_fields": { "last_name": null, "first_name": null, "company_name": "TestBeneficiaryCompany", "identification_type": "company_registered_number", "identification_value": "123456789" }, "payout_method_types_include": null, "payout_method_types_exclude": null, "complete_url": null, "cancel_url": null } } ``` ### Redirect Your Customer Redirect your customer to the URL you received in the `redirect_url` field for the response. > **Note:** > > The hosted beneficiary page expires 14 days after creation by default. ### Gathering Information on the Hosted Page The end user or beneficiary will enter in their details on the hosted page below. ![6480848894774.png](image/img-56e1e4050de7b4cdf56b5d74e0aee1ca.png) - Hosted pages can be customized using the Client Portal as described in [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page") . - The following languages are supported: English, Icelandic, German, Spanish, Simplified Chinese, Traditional Chinese, Korean, Portuguese, Thai, Indonesian, and Tagalog. Specify your language preference in the language parameter field when generating the page. ### Generate IDs for Each Beneficiary - Rapyd generates a beneficiary ID to represent each beneficiary submitted through the hosted page form. You will receive the beneficiary IDs in the [Webhook - Beneficiary Created](https://docs.rapyd.net/en/beneficiary-created-webhook.md "Beneficiary Created Webhook") after the form is submitted. > **Note:** > > When beneficiary information is captured, Rapyd sends a webhook. Configure your system to receive webhooks with the procedure described in [Defining a Webhook Endpoint](https://docs.rapyd.net/en/defining-a-webhook-endpoint.md "Defining a Webhook Endpoint") . ### Create Payout You can now use these beneficiary IDs to process payouts with Rapyd Disburse using [Create Payout](https://docs.rapyd.net/en/create-payout.md "Create Payout") or [Mass Payouts](https://docs.rapyd.net/en/mass-payouts.md "Mass Payouts") in the Client Portal. ### Beneficiary Account Details Toolkit Integration Before embedding the toolkit into your page, follow steps 1 and 2 to create your Hosted Beneficiary Account Details Page. Once you create the hosted page, in the API response, you’ll receive the ID of the Beneficiary Account Details Hosted page object, a string starting with hp*ben*, (for example: id: "hp_ben_d0e257f33e5ef13956ac6037ccb36909"). Add the following code to your Beneficiary Account Details page: 1. Add a ``` **Note**: To run this method in the [sandbox](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_sandbox "Sandbox"), use the following code: ```programming_language_name ``` 2. Add a tag with `id="rapyd-toolkit"`: ```programming_language_name
``` 3. Initialize the Beneficiary Account Details with the following fields: - - Javascript - ``` lettoolkit=newRapydToolkit({ button_text: "Submit", // Text that appears on the 'Submit' button. // String. Maximum length is 16 characters. // Default is "Place Your Order". Optional. button_color: "blue", // Color of the 'Submit' button. String. // Standard CSS color name or hexadecimal code such as #323fff. // Default is the color that is returned in the 'merchant_color' // field of the response to 'Create Beneficiary Account Details Page'. Optional.id: "hp_ben_d0e257f33e5ef13956ac6037ccb36909", // ID of the 'Create Beneficiary Account Details Page' response. String. Required.close_on_complete: true, // Causes the embedded Rapyd Beneficiary Account Details Toolkit window to close // when the submission is complete. Boolean. Default is 'true'. Optional. page_type: “beneficiary_token” /* Mandatory for beneficiary account details page Default is "collection". */ }); ``` 4. Call display Toolkit() to display the Beneficiary Account Details page. ```programming_language_name toolkit.displayToolkit(); ``` 5. Optional step. If `close_on_complete` is set to **false**, call `toolkit.closeToolkit()` to close the Rapyd Beneficiary Account Details Toolkit window. ```programming_language_name toolkit.closeToolkit(); ``` 6. Insert your code that runs when the following events occur. Use your code to read the event field in the window object. - - Javascript - ``` { window.addEventListener('onCreateBeneficiarySuccess', (event) => { console.log(event.detail) // Returns 'Beneficiary' object.// Client code. }) window.addEventListener('onBeneficiaryFailure', (event) => { console.error(event.detail.error) // Returns an error message from the API.// Client code. }) window.addEventListener('onLoading', (event) => { console.error(event.detail.error) // returns true or false depending on the loading state// client code }) ``` ### Sample Embedded Beneficiary Account Details Here's an example of a Beneficiary Account Details page created using the Toolkit: - - HTML - ``` Rapyd Beneficiary Account Details Toolkit

Rapyd Beneficiary Account Details Toolkit Demo

``` > **Note:** > > On successful submission, the clients receive an **onCreateBeneficiarySuccess** event with the [Beneficiary Object](https://docs.rapyd.net/en/beneficiary.md "Beneficiary"). Take note of the following Beneficiary Object fields and the tasks associated with each of them. | Field | Description | Action | | --- | --- | --- | | `id` | ID of the 'beneficiary' object. String starting with beneficiary_. | You can capture the beneficiary ID which is the unique identifier of the individual or company receiving the payout. Use the ID to validate or retrieve the beneficiary. | | `entity_type` | Type of entity. One of the following values: individual company | An individual may include more personal information. Their first name and last name should match the name on the identification_type. | | `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 should be the identification number on the document. | **Recommendation**: Be sure to implement navigation elements (e.g. back, return, or cancel) on your website when embedding the Toolkit Integration solution. > **Note:** > > When beneficiary information is captured, Rapyd sends a webhook. Configure your system to receive webhooks with the procedure described in [Defining a Webhook Endpoint](https://docs.rapyd.net/en/defining-a-webhook-endpoint.md "Defining a Webhook Endpoint").