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.

Payout to a Bank Account Workflow

Finding the specific bank payout methods that match the country and currency you'll support is described under How it Works.

Step 1: Requesting a Payout

On your website, your payroll manager requests a payout for an employee's salary.
The website back end asks Rapyd to process the payout.

Step 2: Processing the Payout

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.

Bank Payout Message Sequences

The message sequence diagrams below describe how information is exchanged between Rapyd, the merchant, and the bank.

Create Bank Payout - Success

Create Bank Payout - Failure

How a Bank Payout 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 company wallet of the ride-sharing service. Use the ID you get in the response.

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).

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.

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 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
`account_number`
	`address`
	`beneficiary_relationship`
	`company_name`
	`date_of_birth`
`first_name`
`last_name`
`identification_type`	`identification_type`
`identification_value`	`identification_value`
`phone_number`	`phone_number`
	`occupation`
	`purpose_code`
	`source_of_income`

Tip

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

Requesting a Payout

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: `first_name` - Enter Test `last_name` - Enter Driver `account_number` - Enter 006449956988 `identification_type` - Enter international passport `identification_value` - Enter Z4703384 `phone_number` - Enter 632567000014
sender	Enter a 'sender' object that has the following fields: `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
description	Enter Salary payout - wallet to bank account as the description of the payout transaction.

Create Payout Request

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)

Create Payout Response

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 for status.
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 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.

In this section:

Documentation

Bank Account Payout

Payout to a Bank Account Workflow

Step 1: Requesting a Payout

Step 2: Processing the Payout

Bank Payout Message Sequences

How a Bank Payout 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

Tip

Requesting a Payout

Create Payout Request

Create Payout Response

Closing the Transaction

Simulating Payout Completion

Looking for More In-Depth Technical Information?

Search results