Reusing Beneficiary or Sender

Streamline your future payouts. | Enterprise

Rapyd streamlines payouts and makes it easy to reuse beneficiary and sender information. Rapyd creates IDs to represent each contact to avoid entering detail information each payout.

For example, your payroll manager can get IDs that represent the beneficiary and sender in a salary payout. The payroll manager can use these IDs for each monthly salary payout. This avoids the need to manually reenter detailed information for each payout.

Common use cases include:

On-going payout to a business or businesses in a marketplace
On-going payouts to a contract worker or employee
Payout to suppliers (B2B) that provide for your business

Reuse Workflow

Finding the specific payout methods you'll use is described under How it Works.

Step 1: Getting a Sender ID

On your website, your payroll manager requests an ID for the sender.
The website back end asks Rapyd to create a sender ID.
Rapyd sends a sender ID to the website back end.
Your payroll manager receives the sender ID from your website.

Step 2: Getting a Beneficiary ID

Your payroll manager requests an ID for the beneficiary.
The website back end asks Rapyd to create a beneficiary ID .
Rapyd sends a beneficiary ID to the website backend.
Your payroll manager receives the beneficiary ID from your website.

Step 3: Using IDs for a Payout

Your payroll manager requests a payout for an employee's salary, specifying the sender and beneficiary IDs.
The website back end asks Rapyd to process the payout.
Rapyd processes the payout.
The website back end receives confirmation from Rapyd that the payout was completed.

How Reusing a Beneficiary or Sender Works

Prerequisites

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

ewallet - Run Create Wallet for the Wallet of the ride-sharing service. Use the 'id' you get in the response. For more information, see Creating a Rapyd Wallet .

Finding Payout Method Types

For your payout page, you need to find payout method types that match your criteria, such as the payout currency and category (for example, bank or cash).

In this example, you'll find payout method types that support bank transfers in PHP (Philippine Pesos).

For that, you'll use List Payout Method Types with the following parameters:

Description of Query Parameters

Query Parameter	Description
category	Enter bank as the category of the payout method.
beneficiary_country	Enter PH as the code for the Philippines, the beneficiary's country.
payout_currency	Enter PHP as the code for Philippine Pesos, the currency received by the beneficiary.

List Payout Method Types Request

You ask for a list of all available payout method types for bank transfers in PHP (Philippine Pesos).

Request

// Request URL: GET https://sandboxapi.rapyd.net/v1/payout_methods?category=bank&beneficiary_country=PH&payout_currency=PHP

// Message body absent

.NET Core

using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string category = "bank";
                string beneficiaryCountry = "PH";
                string payoutCurrency = "PHP";

                string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payout_methods?category={category}&beneficiary_country={beneficiaryCountry}&payout_currency={payoutCurrency}");

                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 result = await makeRequest('GET', '/v1/payout_methods?category=bank&beneficiary_country=PH&payout_currency=PHP');
    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);

try {
    $object = make_request('get', "/v1/payout_methods?category=bank&beneficiary_country=PH&payout_currency=PHP");
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

beneficiary_country = 'PH'
category = 'bank'
payout_currency = 'PHP'

path = f'/v1/payout_methods?category={category}&' \
       f'beneficiary_country={beneficiary_country}&' \
       f'payout_currency={payout_currency}'
methods = make_request(method='get', path=path)
pprint(methods)

List Payout Method Types Response

Let's take a look at the response.

Response

{
        "status": {
                "error_code": "",
                "status": "SUCCESS",
                "message": "",
                "response_code": "",
                "operation_id": "f5b4ebce-b159-427e-b424-62aba58f8cd8"
        },
        "data": [{
                        "payout_method_type": "ph_anzbank_bank",
                        "name": "Bank Transfer to ANZ Bank in the Philippines",
                        "is_cancelable": 0,
                        "is_expirable": 0,
                        "is_location_specific": 0,
                        "is_online": 0,
                        "status": 1,
                        "image": "",
                        "category": "bank",
                        "beneficiary_country": "ph",
                        "payout_currencies": [
                                "PHP"
                        ],
                        "sender_entity_types": [
                                "company",
                                "individual"
                        ],
                        "beneficiary_entity_types": [
                                "company",
                                "individual"
                        ],
                        "amount_range_per_currency": [{
                                        "maximum_amount": null,
                                        "minimum_amount": null,
                                        "payout_currency": "PHP"
                                }
                        ]
                }
        ]
}

The data section of this response shows that ph_anzbank_bank is an acceptable payout method type for bank transfers in PHP (Philippine Pesos).

A real response usually lists many payout methods.

Finding Required Fields for the Payout Method Type

You need to find the required fields for each payout method type.

For that, you'll use Get Payout Required Fields with the following parameters:

Description of Path Parameters

Path Parameter	Description
payout_method_type	Enter ph_anzbank_bank as the payout method type.

Description of Query Parameters

Query Parameter	Description
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.
beneficiary_country	Enter PH as the code for the Philippines, the beneficiary's country.
payout_currency	Enter PHP as the code for Philippine Pesos, the currency received by the beneficiary.
sender_entity_type	Enter company as the type of entity for the sender.
beneficiary_entity_type	Enter individual as the type of entity for the beneficiary.
payout_amount	Enter 10000 as the amount received by the beneficiary.

Get Payout Required Fields Request

You ask for the set of required fields for the ph_anzbank_bank payout method type.

Request

// Request URL: GET https://sandboxapi.rapyd.net/v1/payout_methods/ph_anzbank_bank/required_fields?sender_country=GB&sender_currency=PHP&beneficiary_country=PH&payout_currency=PHP&sender_entity_type=company&beneficiary_entity_type=individual&payout_amount=10000

// Message body absent

.NET Core

using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string payoutMethodType = "ph_anzbank_bank";
                string senderCountry = "GB";
                string senderCurrency = "PHP";
                string beneficiaryCountry = "PH";
                string payoutCurrency = "PHP";
                string senderEntityType = "company";
                string beneficiaryEntityType = "individual";
                string payoutAmount = "10000";

                string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payout_methods/{payoutMethodType}/required_fields?sender_country={senderCountry}&sender_currency={senderCurrency}&beneficiary_country={beneficiaryCountry}&payout_currency={payoutCurrency}&sender_entity_type={senderEntityType}&beneficiary_entity_type={beneficiaryEntityType}&payout_amount={payoutAmount}");

                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 result = await makeRequest(
      'GET',
      '/v1/payout_methods/ph_anzbank_bank/required_fields?sender_country=GB&sender_currency=PHP&beneficiary_country=PH&payout_currency=PHP&sender_entity_type=company&beneficiary_entity_type=individual&payout_amount=10000'
    );
    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);

try {
    $object = make_request('get', "/v1/payout_methods/ph_anzbank_bank/required_fields?sender_country=GB&sender_currency=PHP&beneficiary_country=PH&payout_currency=PHP&sender_entity_type=company&beneficiary_entity_type=individual&payout_amount=10000");
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

payout_method_type = 'ph_anzbank_bank'
beneficiary_country = 'PH'
sender_country = 'GB'
beneficiary_entity_type = 'individual'
sender_entity_type = 'company'
payout_amount = 10000
payout_currency = 'PHP'
sender_currency = 'PHP'

path = f'/v1/payout_methods/{payout_method_type}/required_fields?sender_country={sender_country}&sender_currency={sender_currency}&' \
       f'beneficiary_country={beneficiary_country}&payout_currency={payout_currency}&' \
       f'sender_entity_type={sender_entity_type}&beneficiary_entity_type={beneficiary_entity_type}&payout_amount={payout_amount}'
required_fields = make_request(method='get', path=path)
pprint(required_fields)

Get Payout Required Fields Response

Let's take a look at the response.

Response

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "f3b51074-63f6-436b-9294-6fb6361a098d"
    },
    "data": {
        "payout_method_type": "ph_anzbank_bank",
        "sender_currency": "PHP",
        "sender_country": "*",
        "sender_entity_type": "company",
        "beneficiary_country": "ph",
        "payout_currency": "PHP",
        "beneficiary_entity_type": "individual",
     
//      ...          
          
        "beneficiary_required_fields": [
            {
                "name": "first_name",
                "regex": "^([a-zA-Z0-9]){1,50}$)",
                "type": "string"
            },
            {
                "name": "last_name",
                "regex": "^([a-zA-Z0-9]){1,50}$)",
                "type": "string"
            },
            {
                "name": "account_number",
                "regex": "^([a-zA-Z0-9]){1,45}$)",
                "type": "string"
            },
            {
                "name": "identification_type",
                "regex": "(work_permit|international_passport|identification_id|social_security|residence_permit|company_registered_number)",
                "type": "string",
                "description": "identification types"
            },
            {
                "name": "identification_value",
                "regex": "^([a-zA-Z0-9]){1,30}$)",
                "type": "string",
                "description": "alphanumeric characters in length between 1-30"
            }
        ],
        "sender_required_fields": [
            {
                "name": "company_name",
                "regex": "^([a-zA-Z0-9]){1,50}$)",
                "type": "string"
            },
            {
                "name": "identification_type",
                "type": "string",
                "allowed_values": "company_registered_number",
                "description": "identification types"
            },
            {
                "name": "identification_value",
                "regex": "^([a-zA-Z0-9]){1,30}$)",
                "type": "string",
                "description": "alphanumeric characters in length between 1-30"
            },
            {
                "name": "phone_number",
                "regex": "^([0-9]){8,30}$",
                "type": "string",
                "description": "Phone number length between 8-30"
            },
            {
                "name": "occupation",
                "regex": "^([a-zA-Z0-9]){1,50}$)",
                "type": "string"
            },
            {
                "name": "source_of_income",
                "regex": "(business|salary|savings|loans)",
                "type": "string",
                "description": "source of income"
            },
            {
                "name": "date_of_birth",
                "regex": "^([0-2][0-9]|(3)[0-1])(/)(((0)[0-9])|((1)[0-2]))(/)((19|20)[0-9][0-9])$",
                "type": "date",
                "description": "the date must match the following pattern: dd/mm/yyyy"
            },
            {
                "name": "address",
                "regex": "^([a-zA-Z0-9]){2,50}$)",
                "type": "string"
            },
            {
                "name": "purpose_code",
                "regex": "(investment_income|salary|insurance_payments|computer_services|real_estate_abroad|real_estate_in_host_country)",
                "type": "string",
                "description": "purpose code"
            },
            {
                "name": "beneficiary_relationship",
                "regex": "(spouse|children|parent|sibling|brother|sister|self|friend|business partner|customer|employee|branch|subsidiary|holding|supplier)",
                "type": "string",
                "description": "beneficiary relationship"
            }
        ],
      
//    ...          
          
    }
}

The data section of this response shows required fields for ph_anzbank_bank.

You will use the fields listed under beneficiary_required_fields and sender_required_fields when you ask Rapyd to create IDs for the 'beneficiary' and 'sender' objects.

As shown in the following table, some fields are required for both the beneficiary and the sender.

Beneficiary	Sender
`account_number`
	`address`
	`beneficiary_relationship`
	`company_name`
	`date_of_birth`
`first_name`
`identification_type`	`identification_type`
`identification_value`	`identification_value`
`last_name`
	`occupation`
`phone_number`	`phone_number`
	`purpose_code`
	`source_of_income`

Creating a Sender ID

In this example, your payroll manager Jane Doe is the sender of the salary payout.

When Jane requests an ID to represent the 'sender' object in the payout request, you ask Rapyd to create a sender ID.

For that, you'll use Create Sender with the following parameters, which include:

Parameters that are always required for a 'Create Sender' request.
Parameters that are listed under sender_required_fields in the 'Get Payout Required Fields' response for the ph_anzbank_bank payout method type.

Description of Body Parameters

Body Parameter	Description
country	Enter GB as the code for the United Kingdom, the sender's country.
currency	Enter PHP as the code for Philippine pesos, the sender's currency.
entity_type	Enter company as the type of entity for the sender.
company_name	Enter Four Star Rideshare Service.
identification_type	Enter company registered number.
identification_value	Enter 10207686 .
phone_number	Enter 442037443095 .
occupation	Enter transportation .
source_of_income	Enter business .
date_of_birth	Enter 31/07/1984 .
address	Enter 123 Main Street London.
purpose_code	Enter salary.
beneficiary_relationship	Enter employee .

Create Sender Request

You ask Rapyd to process Jane's request for a sender ID.

Request

// Request URL: POST https://sandboxapi.rapyd.net/v1/payouts/sender

// Message body:
{
        "country": "GB",
        "currency": "PHP",  
        "entity_type": "company",
        "company_name": "Four Star Rideshare Service",
        "identification_type": "company registered number",
        "identification_value": "10207686",
        "phone_number": "442037443095",
        "occupation": "transportation",
        "source_of_income": "business",
        "date_of_birth": "31/07/1984",
        "address": "123 Main Street London",
        "purpose_code": "salary",
        "beneficiary_relationship": "employee"
}

.NET Core

using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {

                var requestObj = new
                {

                    country = "GB",
                    currency = "PHP",
                    entity_type = "company",
                    company_name = "Four Star Rideshare Service",
                    identification_type = "company registered number",
                    identification_value = "10207686",
                    phone_number = "442037443095",
                    occupation = "transportation",
                    source_of_income = "business",
                    date_of_birth = "31/07/1984",
                    address = "123 Main Street London",
                    purpose_code = "salary",
                    beneficiary_relationship = "employee"
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payouts/sender", 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 = {
      country: 'GB',
      currency: 'PHP',
      entity_type: 'company',
      company_name: 'Four Star Rideshare Service',
      identification_type: 'company registered number',
      identification_value: '10207686',
      phone_number: '442037443095',
      occupation: 'transportation',
      source_of_income: 'business',
      date_of_birth: '31/07/1984',
      address: '123 Main Street London',
      purpose_code: 'salary',
      beneficiary_relationship: 'employee'
    };
    const result = await makeRequest('POST', '/v1/payouts/sender', 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 = [
    "country" => "GB",
    "currency" => "PHP",
    "entity_type" => "company",
    "company_name" => "Four Star Rideshare Service",
    "identification_type" => "company registered number",
    "identification_value" => "10207686",
    "phone_number" => "442037443095",
    "occupation" => "transportation",
    "source_of_income" => "business",
    "date_of_birth" => "31/07/1984",
    "address" => "123 Main Street London",
    "purpose_code" => "salary",
    "beneficiary_relationship" => "employee"
];

try {
    $object = make_request('post', '/v1/payouts/sender', $body);
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

# Create Sender request
body = {
    "country": "GB",
    "currency": "PHP",
    "entity_type": "company",
    "company_name": "Four Star Rideshare Service",
    "identification_type": "company registered number",
    "identification_value": "10207686",
    "phone_number": "442037443095",
    "occupation": "transportation",
    "source_of_income": "business",
    "date_of_birth": "31/07/1984",
    "address": "123 Main Street London",
    "purpose_code": "salary",
    "beneficiary_relationship": "employee"
}
results = make_request(method='post',
                       path='/v1/payouts/sender',
                       body=body)
pprint(results)

Create Sender Response

Let's take a look at the response.

Response

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "790974a1-5600-4f38-b8b5-c9cd10deda1c"
    },
    "data": {
        "id": "sender_2c3d6492f50f7de237b867bb3e40a247",
        "country": "GB",
        "entity_type": "company",
        "address": "123 Main Street London",
        "name": "Four Star Rideshare Service",
        "date_of_birth": "31/07/1984",
        "phone_number": "442037443095",
        "company_name": "Four Star Rideshare Service",
        "currency": "PHP",
        "identification_type": "company registered number",
        "identification_value": "10207686",
        "purpose_code": "salary",
        "beneficiary_relationship": "employee",
        "source_of_income": "business",
        "occupation": "transportation"
    }
}

The data section of this response shows:

The id for the sender is sender_2c3d6492f50f7de237b867bb3e40a247. When you run this example in your own sandbox, you will get a different ID, which you will need for a later step in this use case.
Fields of the 'sender' object that the ID represents are listed.

Requesting a Beneficiary ID

In this example, John Doe (the employee) is the beneficiary who receives the salary payout.

When your payroll manager Jane requests an ID to represent the 'beneficiary' object in the payout request, you ask Rapyd to create a beneficiary ID.

For that, you'll use Create Beneficiary with the following parameters, which include:

Parameters that are always required for a 'Create Beneficiary' request.
Parameters that are listed under beneficiary_required_fields in the 'Get Payout Required Fields' response for the ph_anzbank_bank payout method type.

Description of Body Parameters

Body Parameter	Description
category	Enter bank as the category of the payout method.
country	Enter PH as the code for the Philippines, the beneficiary's country.
currency	Enter PHP as the code for Philippine Pesos, the currency received by the beneficiary.
entity_type	Enter individual as the type of entity for the beneficiary.
first_name	Enter John as the first name of the beneficiary.
last_name	Enter Doe as the last name of the beneficiary.
account_number	Enter 006449956988 .
identification_type	Enter international passport.
identification_value	Enter Z4703384 .
phone_number	Enter 632567000014 .

Note

You can also create a beneficiary object with Create Beneficiary Tokenization Page. When the process is complete, Rapyd sends you Webhook - Beneficiary Created, which contains the beneficiary ID.

Create Beneficiary Request

You ask Rapyd to process Jane's request for a beneficiary ID.

Request

// Request URL: POST https://sandboxapi.rapyd.net/v1/payouts/beneficiary

// Message body:
{
        "category": "bank",
        "country": "PH",
        "currency": "PHP",
        "entity_type": "individual",
        "first_name": "John",
        "last_name": "Doe",
        "account_number": "006449956988",
        "identification_type": "international passport",
        "identification_value": "Z4703384",
        "phone_number": "632567000014"
}

.NET Core

using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {

                var requestObj = new
                {
                    category = "bank",
                    country = "PH",
                    currency = "PHP",
                    entity_type = "individual",
                    first_name = "John",
                    last_name = "Doe",
                    account_number = "006449956988",
                    identification_type = "international passport",
                    identification_value = "Z4703384",
                    phone_number = "632567000014"
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payouts/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',
      country: 'PH',
      currency: 'PHP',
      entity_type: 'individual',
      first_name: 'John',
      last_name: 'Doe',
      account_number: '006449956988',
      identification_type: 'international passport',
      identification_value: 'Z4703384',
      phone_number: '632567000014'
    };
    const result = await makeRequest('POST', '/v1/payouts/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",
    "country" => "PH",
    "currency" => "PHP",
    "entity_type" => "individual",
    "first_name" => "John",
    "last_name" => "Doe",
    "account_number" => "006449956988",
    "identification_type" => "international passport",
    "identification_value" => "Z4703384",
    "phone_number" => "632567000014"
];

try {
    $object = make_request('post', '/v1/payouts/beneficiary', $body);
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

beneficiary_details = {
    "category": "bank",
    "country": "PH",
    "currency": "PHP",
    "entity_type": "individual",
    "first_name": "John",
    "last_name": "Doe",
    "account_number": "006449956988",
    "identification_type": "international passport",
    "identification_value": "Z4703384",
    "phone_number": "632567000014"
}

result = make_request(method='post',
                      path='/v1/payouts/beneficiary',
                      body=beneficiary_details)
pprint(result)

Create Beneficiary Response

Let's take a look at the response.

Response

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "1fb218a9-e5a4-4cc0-8377-27d52f18d133"
    },
    "data": {
        "id": "beneficiary_a0345a157ccac51bf4d4a54b388c32ba",
        "last_name": "Doe",
        "first_name": "John",
        "country": "PH",
        "entity_type": "individual",
        "name": "John Doe",
        "phone_number": "632567000014",
        "currency": "PHP",
        "identification_type": "international passport",
        "identification_value": "Z4703384",
        "category": "bank"
    }
}

The data section of this response shows:

The id for the beneficiary is beneficiary_a0345a157ccac51bf4d4a54b388c32ba. When you run this example in your own sandbox, you will get a different ID, which you will need for a later step in this use case.
Fields of the 'beneficiary' object that the ID represents are listed.

Tip

Use Validate Beneficiary to check the beneficiary fields before you request the payout. See Validating Beneficiary Details .

Requesting a Payout

When Jane requests a payout from the company wallet to John's bank account, you ask Rapyd to process the payout.

For that, you'll use Create Payout with the following parameters:

Description of Body Parameters

Body Parameter	Description
ewallet	Enter the wallet 'id' that you received when you created the company wallet in your sandbox. For purposes of this use case lesson, we are using ewallet_090e1ef18c3aa754fd43cce9ee454858, which is the wallet ID we created in our sandbox.
payout_amount	Enter 10000 as the amount received by the beneficiary.
payout_method_type	Enter ph_anzbank_bank as the payout method type.
sender_currency	Enter PHP as the code for Philippine Pesos, the sender's currency.
sender_country	Enter GB as the code for the United Kingdom, the sender's country.
beneficiary_country	Enter PH as the code for the Philippines, the beneficiary's country.
payout_currency	Enter PHP as the code for Philippine Pesos, the currency received by the beneficiary.
sender_entity_type	Enter company as the type of entity for the sender.
beneficiary_entity_type	Enter individual as the type of entity for the beneficiary.
beneficiary	Enter the beneficiary 'id' that you received when you created the beneficiary 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.
sender	Enter the sender 'id' that you received when you created the sender in your sandbox. For purposes of this use case lesson, we are using sender_2c3d6492f50f7de237b867bb3e40a247, which is the sender ID we created in our sandbox.
description	Enter Salary payout - eWallet to bank account as the description of the payout transaction.

Create Payout Request

You ask Rapyd to process Jane's payout of 10,000 PHP (Philippine Pesos) to John's bank account.

Request

// Request URL: POST https://sandboxapi.rapyd.net/v1/payouts

// Message body: 
{
        "ewallet": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
        "payout_amount": 10000,
        "payout_method_type": "ph_anzbank_bank",
        "sender_currency": "PHP",
        "sender_country": "GB",
        "beneficiary_country": "PH",
        "payout_currency": "PHP",
        "sender_entity_type": "company",
        "beneficiary_entity_type": "individual",
        "beneficiary": "beneficiary_a0345a157ccac51bf4d4a54b388c32ba",
        "sender": "sender_2c3d6492f50f7de237b867bb3e40a247",
        "description": "Salary payout - wallet to bank account"
}

.NET Core

using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var requestObj = new
                {
                    ewallet = "ewallet_090e1ef18c3aa754fd43cce9ee454858",
                    payout_amount = 10000,
                    payout_method_type = "ph_anzbank_bank",
                    sender_currency = "PHP",
                    sender_country = "GB",
                    beneficiary_country = "PH",
                    payout_currency = "PHP",
                    sender_entity_type = "company",
                    beneficiary_entity_type = "individual",
                    beneficiary = "beneficiary_a0345a157ccac51bf4d4a54b388c32ba",
                    sender = "sender_2c3d6492f50f7de237b867bb3e40a247",
                    description = "Salary payout - eWallet to bank account"
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payouts", 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 = {
      ewallet: 'ewallet_090e1ef18c3aa754fd43cce9ee454858',
      payout_amount: 10000,
      payout_method_type: 'ph_anzbank_bank',
      sender_currency: 'PHP',
      sender_country: 'GB',
      beneficiary_country: 'PH',
      payout_currency: 'PHP',
      sender_entity_type: 'company',
      beneficiary_entity_type: 'individual',
      beneficiary: 'beneficiary_a0345a157ccac51bf4d4a54b388c32ba',
      sender: 'sender_2c3d6492f50f7de237b867bb3e40a247',
      description: 'Salary payout - wallet to bank account'
    };
    const result = await makeRequest('POST', '/v1/payouts', 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 = [
    'ewallet' => "ewallet_090e1ef18c3aa754fd43cce9ee454858",
    "payout_amount" => 10000,
    "payout_method_type" => "ph_anzbank_bank",
    "sender_currency" => "PHP",
    "sender_country" => "GB",
    "beneficiary_country" => "PH",
    "payout_currency" => "PHP",
    "sender_entity_type" => "company",
    "beneficiary_entity_type" => "individual",
    "beneficiary" => "beneficiary_a0345a157ccac51bf4d4a54b388c32ba",
    "sender" => "sender_2c3d6492f50f7de237b867bb3e40a247",
    "description" => "Salary payout - eWallet to bank account"
];

try {
    $object = make_request('post', '/v1/payouts', $body);
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

payout_body = {
    "ewallet": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
    "payout_amount": 10000,
    "payout_method_type": "ph_anzbank_bank",
    "sender_currency": "PHP",
    "sender_country": "GB",
    "beneficiary_country": "PH",
    "payout_currency": "PHP",
    "sender_entity_type": "company",
    "beneficiary_entity_type": "individual",
    "beneficiary": "beneficiary_a0345a157ccac51bf4d4a54b388c32ba",
    "sender": "sender_2c3d6492f50f7de237b867bb3e40a247",
    "description": "Salary payout - eWallet to bank account"
}

result = make_request(method='post', path='/v1/payouts', body=payout_body)
pprint(result)

Create Payout Response

Let's take a look at the response.

Response

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "90e4b733-accd-4d1d-a2b0-43c6374d0b56"
    },
    "data": {
        "id": "payout_13b1eb7d39ba9be479df4e28b7f1716d",
        "payout_type": "bank",
        "payout_method_type": "ph_anzbank_bank",
        "amount": 10000,
        "payout_currency": "PHP",
        "sender_amount": 10000,
        "sender_currency": "PHP",
        "status": "Created",
        "sender_country": "GB",
        "sender": {
            "id": "sender_2c3d6492f50f7de237b867bb3e40a247",
            "country": "GB",
            "entity_type": "company",
            "address": "123 Main Street London",
            "name": "Four Star Rideshare Service",
            "date_of_birth": "31/07/1984",
            "phone_number": "442037443095",
            "company_name": "Four Star Rideshare Service",
            "currency": "PHP",
            "identification_type": "company registered number",
            "identification_value": "10207686",
            "purpose_code": "salary",
            "beneficiary_relationship": "employee",
            "source_of_income": "business",
            "occupation": "transportation"
        },
        "beneficiary_country": "PH",
        "beneficiary": {
            "id": "beneficiary_a0345a157ccac51bf4d4a54b388c32ba",
            "last_name": "Doe",
            "first_name": "John",
            "country": "PH",
            "entity_type": "individual",
            "name": "John Doe",
            "phone_number": "632567000014",
            "account_number": "006449956988",
            "currency": "PHP",
            "identification_type": "international passport",
            "identification_value": "Z4703384",
            "bank_name": "John Doe",
            "category": "bank"
        },
        "fx_rate": 1,
        "instructions": {
            "name": "instructions",
            "steps": [
                {
                    "step1": "The funds will be transferred to the provided account details of the beneficiary ."
                }
            ]
        },
        "ewallets": [
            {
                "ewallet_id": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
                "amount": 10000,
                "percent": 100
            }
        ],
        "metadata": {},
        "description": "Salary payout - wallet to bank account",
      
//    ...          
          
    }
}

Besides parameter values that you entered in the request, the data section of this response shows:

The id of the 'payout' object is payout_13b1eb7d39ba9be479df4e28b7f1716d. Webhooks that relate to this payout refer to this ID.
The payout_type is bank.
Under sender:
- The id is sender_2c3d6492f50f7de237b867bb3e40a247 .
- Fields of the 'sender' object that the ID represents are listed.
Under beneficiary:
- The id is beneficiary_a0345a157ccac51bf4d4a54b388c32ba .
- Fields of the 'beneficiary' object that the ID represents are listed.
The status is Created. This means that the 'payout' object was created successfully and John did not yet receive the payout funds.
There are instructions that describe the transfer of funds to the beneficiary bank account.

Closing the Transaction

Simulating Payout Completion

The sandbox does not directly simulate the action of the beneficiary receiving the payout funds. You can simulate this action with the procedure described in Complete Payout. For this, you will need the payout ID and payout amount that you generated in your sandbox.

When a payout completion is simulated, Rapyd sends a webhook. Configure your system to receive webhooks with the procedure described in Defining a Webhook Endpoint.

After you simulate that John's bank account was credited with his salary, Rapyd sends you Webhook - Payout Completed. The webhook confirms that the payout was completed.

Reusing IDs

The sender and beneficiary IDs represent objects containing the values of the required fields listed when the 'Get Payout Required Fields' response was generated.

You can use the IDs for any payout method with required fields that all match fields that were required when the IDs were created. The IDs are valid for a payout method that has fewer required fields, but not for a payout method with any additional or different required fields.

Note

The required fields for the original payout method may change over time.

If you cannot use an existing ID, do one of the following:

Get a new ID using the methods described above. To create an ID that you can use with multiple payout methods, include all fields that are required by each payout method.
Manually insert the object with all of the required field values, as described in Payout to a Bank Account .

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

Reusing Beneficiary or Sender

Reuse Workflow

Step 1: Getting a Sender ID

Step 2: Getting a Beneficiary ID

Step 3: Using IDs for a Payout

How Reusing a Beneficiary or Sender Works

Prerequisites

Finding Payout Method Types

List Payout Method Types Request

List Payout Method Types Response

Finding Required Fields for the Payout Method Type

Get Payout Required Fields Request

Get Payout Required Fields Response

Creating a Sender ID

Create Sender Request

Create Sender Response

Requesting a Beneficiary ID

Note

Create Beneficiary Request

Create Beneficiary Response

Tip

Requesting a Payout

Create Payout Request

Create Payout Response

Closing the Transaction

Simulating Payout Completion

Reusing IDs

Note

Need More In-Depth Technical Information?

Search results