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

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.
  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 - 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.
- language
- Determines the default language of the hosted page. For a list of values, see 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. 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.
- 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.
- 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.
- 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.
  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.
- merchant_customer_support
- Contains details of the client’s customer support. To configure these fields, use the Client Portal. See 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.
- 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.
- page_expiration
- End of the time when the customer can use the hosted page, in 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.
- tokenization_page
- ID of the beneficiary tokenization page. String starting with hp_ben_.

Code Samples

.NET

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

const makeRequest = require('<path-to-your-utility-file>/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
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/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

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 -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"
}'

{
    "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 -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"
}'

{
    "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 -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"
}'

{
    "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
    }
}

Related Information

Beneficiary Account Details

In this section:

Documentation

Create Beneficiary Tokenization Page

Note

Parameters

Request Header Parameters

Request Body Parameters

Note

Note

Response Parameters

Code Samples

Related Information

Search results