--- title: "Validating Beneficiary Details" source_url: https://docs.rapyd.net/en/validating-beneficiary-details.html lang: en --- # Validating Beneficiary Details Verify your beneficiaries to receive payouts. | `Enterprise` Before you use a [beneficiary](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_beneficiary "Beneficiary") ID in creating a payout, Rapyd recommends that you verify that no mistakes were made when the ID was created. To do this, you validate the beneficiary's details for the relevant payout method type. For example, your ride-sharing service, has a website or mobile application that is registered on the Rapyd platform. Your payroll manager uses a [company wallet](https://docs.rapyd.net/en/creating-a-rapyd-wallet.md "Creating a Rapyd Wallet") to pay the drivers. One of your drivers is an employee who you transfer a monthly salary to from the company wallet to the driver's bank account. In this example, the driver is the payout beneficiary. The payroll manager wants to avoid reentering the driver's details each month. So she got an ID to represent the beneficiary, as described in [Reusing Beneficiary or Sender](https://docs.rapyd.net/en/reusing-beneficiary-or-sender.md "Reusing Beneficiary or Sender"). The beneficiary ID is valid for a payout method with required fields that all match fields that were required when the ID was created. However, required fields for payout methods can change over time. The payroll manager wants to increase the chance that the payout will succeed each month. So before requesting the driver's monthly payout, the manager validates the beneficiary details for the payout method used. ### Validation Workflow Let’s look at the highlights of your workflow. ![validating-beneficiary.jpg](image/img-1f25c41d1921d2b8c66930f89ac28b09.jpg) 1. On your website, your payroll manager asks to [validate a beneficiary](https://docs.rapyd.net/en/validate-beneficiary.md "Validate Beneficiary"). 2. The website back end asks Rapyd to validate the beneficiary. 3. Rapyd processes the validation and sends the result to the website back end. 4. Your payroll manager receives the validation result from your website. ### How Validating Beneficiary Details Works ### Requesting a Validation > **Note:** > > To run the examples of this use case, you must create the following ID in your own [sandbox](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_sandbox "Sandbox"): > > - **beneficiary** - Run [Create Beneficiary](https://docs.rapyd.net/en/create-beneficiary.md "Create Beneficiary") for the employee. Use the **ID** you get in the response. For more information, see [Reusing Beneficiary or Sender](https://docs.rapyd.net/en/reusing-beneficiary-or-sender.md "Reusing Beneficiary or Sender"). When the payroll manager requests validation of the employee's beneficiary ID, you ask Rapyd to validate the beneficiary. For that, you'll use [Validate Beneficiary](https://docs.rapyd.net/en/validate-beneficiary.md "Validate Beneficiary") with the following parameters: Description of Body Parameters | Body Parameter | Description | | --- | --- | | beneficiary | Enter the beneficiary ID that you received when you created the beneficiary for the employee in your sandbox. For purposes of this use case lesson, we are using **beneficiary_a0345a157ccac51bf4d4a54b388c32ba**, which is the beneficiary ID we created in our sandbox. | | payout_method_type | Enter **ph_anzbank_bank** as the payout method type. | | sender_country | Enter **GB** as the code for the United Kingdom, the sender's country. | | sender_currency | Enter **PHP** as the code for Philippine pesos, the sender's currency. | | sender_entity_type | Enter **company** as the type of entity for the sender. | | amount | Enter **10000** as the maximum payout amount to validate for the employee. | ### Validate Beneficiary Request You ask Rapyd to validate the beneficiary. - - Request - ``` // Request URL: POST https://sandboxapi.rapyd.net/v1/payouts/beneficiary/validate // Message body: { "beneficiary": "beneficiary_a0345a157ccac51bf4d4a54b388c32ba", "payout_method_type": "ph_anzbank_bank", "sender_country": "GB", "sender_currency": "PHP", "sender_entity_type": "company", "amount": 10000 } ``` - - .NET Core - ``` using System; using System.Text.Json; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { var requestObj = new { beneficiary = "beneficiary_a0345a157ccac51bf4d4a54b388c32ba", payout_method_type = "ph_anzbank_bank", sender_country = "GB", sender_currency = "PHP", sender_entity_type = "company", amount = 10000 }; string request = JsonSerializer.Serialize(requestObj); string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payouts/beneficiary/validate", request); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ``` const makeRequest = require('/utilities').makeRequest; async function main() { try { const body = { beneficiary: 'beneficiary_a0345a157ccac51bf4d4a54b388c32ba', payout_method_type: 'ph_anzbank_bank', sender_country: 'GB', sender_currency: 'PHP', sender_entity_type: 'company', amount: 10000 }; const result = await makeRequest('POST', '/v1/payouts/beneficiary/validate', body); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ``` /utilities.php"; include($path); $body = [ "beneficiary" => "beneficiary_a0345a157ccac51bf4d4a54b388c32ba", "payout_method_type" => "ph_anzbank_bank", "sender_country" => "GB", "sender_currency" => "PHP", "sender_entity_type" => "company", "amount" => 10000 ]; try { $object = make_request('post', '/v1/payouts/beneficiary/validate', $body); var_dump($object); } catch (Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ``` from pprint import pprint from utilities import make_request beneficiary_info = { "beneficiary": 'beneficiary_a0345a157ccac51bf4d4a54b388c32ba', "payout_method_type": "ph_anzbank_bank", "sender_country": "GB", "sender_currency": "PHP", "sender_entity_type": "company", "amount": 10000 } results = make_request(method='post', path='/v1/payouts/beneficiary/validate', body=beneficiary_info) pprint(results) ``` ### Validate Beneficiary Response Let's take a look at the response. - - Response - ``` { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "63c81cc9-3a36-4907-aeb7-27b4316c6af9" }, "data": { "validated": true, "beneficiary": { "id": "beneficiary_a0345a157ccac51bf4d4a54b388c32ba", "last_name": "Name", "first_name": "Test", "country": "PH", "entity_type": "individual", "name": "Test Name", "phone_number": "632567000014", "account_number": "006449956988", "currency": "PHP", "identification_type": "international passport", "identification_value": "Z4703384", "bank_name": "Test Name", "category": "bank" } } } ``` The `data` section of this response shows: - The value of the `validated` field is **true**, meaning that the beneficiary ID is valid with the specified parameters. - The validated beneficiary `id` is **beneficiary_a0345a157ccac51bf4d4a54b388c32ba**. When you run this example in your own sandbox, you will get the ID you entered. - Fields of the 'beneficiary' object that the ID represents are listed. Your website can display the validation results to your payroll manager. > **Note:** > > Want to see the Rapyd API methods and objects that you'll use? Visit the [Merchant API Reference](https://docs.rapyd.net/en/merchant-api-reference.md "Merchant API Reference") for more technical details.