Bank Account Payout
Send funds directly to a bank account. | Enterprise
Rapyd makes it easy for employers to pay employee salaries. An employer can transfer a salary payout from a client wallet directly into an employee's bank account.
Let's consider a case where Four Star Rideshare Service, your ride-sharing service, has a website or mobile application that is registered on the Rapyd platform.
Your payroll manager uses a Rapyd company wallet to pay your drivers. A wallet is created as described in Creating a Rapyd Wallet.
On your website, your payroll manager requests a payout for one of your driver's salary from the company wallet to the driver's bank account. Your website back end asks Rapyd to process the payout. Rapyd processes the payout with the bank. The Rapyd platform notifies your website back end when the payout has been successfully completed.
Finding the specific bank payout methods that match the country and currency you'll support is described under How it Works .
![request-a-payout.jpg](image/166d71f757c82f.jpg)
On your website, your payroll manager requests a payout for an employee's salary.
The website back end asks Rapyd to process the payout.
![process-payout.jpg](image/166d71f75811ba.jpg)
Rapyd processes the payout.
The bank credits the employee's bank account with the money from the company wallet.
Rapyd is notified that the money was credited to the bank account.
The website back end receives confirmation from Rapyd that the payout was completed.
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 company wallet of the ride-sharing service. Use the ID you get in the response.
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).
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('../../../../../Utilities/JS/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 .= "/code_race_2020/Utilities/PHP/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 # List Payout Method Types 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}' results = make_request(method='get', path=path) pprint(results)
List Payout Method Types Response
Let's take a look at the response.
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "479d23c0-a3a3-46ec-82f7-036eb76c0a1a" }, "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" ], "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.
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 beneficiaryCountry = "PH"; string beneficiaryEntityType = "individual"; string payoutAmount = "10000"; string payoutCurrency = "PHP"; string senderCountry = "GB"; string senderCurrency = "PHP"; string senderEntityType = "company"; string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payout_methods/ph_anzbank_bank/required_fields?sender_country={senderCountry}&sender_currency={senderCurrency}&beneficiary_country={beneficiaryCountry}&payout_currency={payoutCurrency}&sender_entity_type={senderEntityType}&beneficiary_entity_type={beneficiaryEntityType}&amount={payoutAmount}"); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } }
JavaScript
const makeRequest = require('../../../../../Utilities/JS/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 .= "/code_race_2020/Utilities/PHP/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 # Get Payout Required Fields 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}&amount={payout_amount}' results = make_request(method='get', path=path) pprint(results)
Get Payout Required Fields Response
Let's take a look at the response.
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "fa3daea3-b71b-4f1d-874b-c44427be36df" }, "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", "is_cancelable": 0, "is_location_specific": 0, "is_expirable": 0, "minimum_expiration_seconds": null, "maximum_expiration_seconds": null, "is_online": 0, "image": "", "status": 1, "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_bdo_bank
.
You will use the required fields for the 'beneficiary' and 'sender' objects when you ask Rapyd to process the payout.
As shown in the following table, some fields are required for both the beneficiary and the sender.
Beneficiary | Sender |
---|---|
| |
| |
| |
| |
| |
| |
| |
|
|
|
|
|
|
| |
| |
|
Tip
Use Validate Beneficiary to check the beneficiary fields before you request the payout. See Validating Beneficiary Details .
In this example, Four Star Rideshare Service is the sender of the payout and the driver (the employee) is the beneficiary who receives the payout.
When your payroll manager requests a payout from the company wallet to the driver'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 a 'beneficiary' object that has the following fields:
|
sender | Enter a 'sender' object that has the following fields:
|
description | Enter Salary payout - wallet to bank account as the description of the payout transaction. |
You ask Rapyd to process your company's payout of 10,000 PHP (Philippine Pesos) to the driver'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": { "first_name": "Test", "last_name": "Driver", "account_number": "006449956988", "identification_type": "international passport", "identification_value": "Z4703384", "phone_number": "632567000014" }, "sender": { "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" }, "description": "Salary payout - wallet to bank account" }
JavaScript
const makeRequest = require('../../../../../Utilities/JS/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', sender_entity_type: 'company', beneficiary_country: 'PH', payout_currency: 'PHP', beneficiary_entity_type: 'individual', beneficiary: { first_name: 'John', last_name: 'Doe', account_number: '006449956988', identification_type: 'international passport', identification_value: 'Z4703384', phone_number: '632567000014' }, sender: { 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' }, 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 .= "/code_race_2020/Utilities/PHP/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" => array( "first_name" => "John", "last_name" => "Doe", "account_number" => "006449956988", "identification_type" => "international passport", "identification_value" => "Z4703384", "phone_number" => "632567000014" ), "sender" => array( "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" ), "description" => "Salary payout - wallet 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 # Create Payout request beneficiary_required_fields = { "first_name": "John", "last_name": "Doe", "account_number": "006449956988", "identification_type": "international passport", "identification_value": "Z4703384", "phone_number": "632567000014" } sender_required_fields = { "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" } 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_required_fields, "sender": sender_required_fields, "description": "Salary payout - wallet to bank account" } result = make_request(method='post', path='/v1/payouts', body=payout_body) pprint(result)
Let's take a look at the response.
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "c76de157-a222-48db-b400-aa5eab1dbe8e" }, "data": { "id": "payout_6805b889dba2250a27d977a55727e34b", "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_024ef0fe5916ab6b54d99cfa9b3164ef", "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_39d9ddb953cdfc457d86d46fbd3aca41", "last_name": "Driver", "first_name": "Test", "country": "PH", "entity_type": "individual", "name": "Test Driver", "phone_number": "632567000014", "currency": "PHP", "identification_type": "international passport", "identification_value": "Z4703384" }, "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", "created_at": 1581256053, "payout_fees": null, "expiration": null, "paid_at": null, "identifier_type": null, "identifier_value": null, "error": null } }
Besides parameter values that you entered in the request, the data
section of this response shows:
The
id
of the 'payout' object is payout_6805b889dba2250a27d977a55727e34b. Webhooks that relate to this payout refer to this ID.The
payout_type
is bank.Under
sender
:The
id
is sender_024ef0fe5916ab6b54d99cfa9b3164ef.Fields of the 'sender' object are listed.
Under
beneficiary
:The
id
is beneficiary_39d9ddb953cdfc457d86d46fbd3aca41 .Fields of the 'beneficiary' object are listed.
The
status
is Created. This means that the 'payout' object was created successfully and the driver did not yet receive the payout funds. Payout Object lists possible values forstatus
.There are instructions that describe the transfer of funds to the beneficiary bank account.
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 the driver's bank account was credited with his salary, Rapyd sends you Webhook - Payout Completed. The webhook confirms that the payout was completed.
Looking for 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.