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.

Validation Workflow

Let’s look at the highlights of your workflow.

On your website, your payroll manager asks to validate a beneficiary.
The website back end asks Rapyd to validate the beneficiary.
Rapyd processes the validation and sends the result to the website back end.
Your payroll manager receives the validation result from your website.

How Validating Beneficiary Details Works

Requesting a Validation

Prerequisite

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

beneficiary - Run Create Beneficiary for the employee. Use the ID you get in the response. For more information, see 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 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('<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);
    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 = [
    "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.

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.

In this section:

Documentation