Skip to main content


Validating Beneficiary Details

Verify your beneficiaries to receive payouts. | Enterprise

Before you use a 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 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. 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.

Let’s look at the highlights of your workflow.

  1. On your website, your payroll manager asks to validate a 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.


To run the examples of this use case, you must create the following ID in your own sandbox:

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 with the following parameters:

Description of Body Parameters

Body Parameter



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.


Enter ph_anzbank_bank as the payout method type.


Enter GB as the code for the United Kingdom, the sender's country.


Enter PHP as the code for Philippine pesos, the sender's currency.


Enter company as the type of entity for the sender.


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
        // 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)
                        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);
                    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 = {
              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);
          } catch (error) {
            console.error('Error completing request', error);
    • PHP

      • <?php
        $path = $_SERVER['DOCUMENT_ROOT'];
        $path .= "/<path-to-your-utility-file>/utilities.php";
        $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);
        } 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',
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.

Need More In-Depth Technical Information?

Want to see the Rapyd API methods and objects that you'll use? Visit the API Reference for more technical details.