Local Bank Payout

Payout with a common, cost effective way to send money via local payment scheme. | Enterprise

Common use cases may include:

Local payout to your own or your customer’s bank account
Local payout to an employee's bank account
Local payout to a supplier (B2B)

A lender wants to disburse a loan booked via a website or mobile application that is integrated on the Rapyd platform.

Your finance manager uses a company wallet to disburse loans into customer bank accounts. Your finance manager starts the process for sending a customer's funds by collecting the routing number and account information.

Your website back end asks Rapyd to process the payout. Rapyd processes the payout. The Rapyd platform notifies your website back end when the payout is complete.

Payout to Bank Account Workflow

Using a payout method such as (gb_local_bank) and the corresponding required fields that beneficiaries fill out is described under How it Works.

Step 1: Requesting a Payout

Collect routing and account information to disburse the funds.
Specify the reason code in the request (for example, salary).
The website back end asks Rapyd to process the payout to a GB bank.

Step 2: Processing the Payout

Rapyd processes the payout to the bank.
The bank credits the customer's bank account with the money from the company wallet.
Rapyd notifies the website back end that the payout is complete.

How a Local Bank Payout Works

Prerequisites

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

ewallet - Run Creating a Rapyd Wallet for the company wallet. Use the 'id' you get in the response. The payout would be funded from the ewallet instructed in the payout request.

Finding Payout Method Types

For the payout page on your website, you need to find payout method types that match your criteria, such as the payout country and currency.

In this example, you'll find local bank payout method types that support transfers in British pounds to a beneficiary in the United Kingdom.

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 GB as the code for the United Kingdom, the beneficiary's country.
payout_currency	Enter GBP as the code for British pounds, the currency received by the beneficiary.

List Payout Method Types Request

You ask for a list of all available bank payout method types for transfers in Great Britain that are done in GBP.

Request

// Request URL: GET https://sandboxapi.rapyd.net/v1/payouts/supported_types?category=bank&beneficiary_country=GB&payout_currency=GBP

// Message body absent

.NET Core

using System;

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

                string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payouts/supported_types?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/payouts/supported_types?category=bank&beneficiary_country=GB&payout_currency=GBP');

    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/payouts/supported_types?category=bank&beneficiary_country=GB&payout_currency=GBP");
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

beneficiary_country = 'GB'
category = 'bank'
payout_currency = 'GBP'

path = f'/v1/payouts/supported_types?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": "5a9fa131-10bb-42b6-8659-934d9fee57a1"
},
"data": [
    "payout_method_type": "gb_local_bank",
        "name": "Local UK payouts",
        "is_cancelable": 0,
        "is_expirable": 0,
        "is_location_specific": 0,
        "status": 1,
        "image": "/checkout/gb_local_bank.png",
        "category": "bank",
        "beneficiary_country": "GB",
        "sender_country": "*",
        "payout_currencies": [
            "GBP"
        ],
        "sender_entity_types": [
            "company",
            "individual"
        ],
        "beneficiary_entity_types": [
            "company",
            "individual"
        ],
        "amount_range_per_currency": [
            {
                "maximum_amount": null,
                "minimum_amount": null,
                "payout_currency": "GBP"
            }
        ],
        "minimum_expiration_seconds": null,
        "maximum_expiration_seconds": null,
        "sender_currencies": [
            "USD",
            "SGD",
            "SEK",
            "ISK",
            "HKD",
            "GBP",
            "EUR",
            "DKK",
            "CHF",
            "AUD"
        ],
        "estimated_time_of_arrival": "An estimated receipt time is not yet available for this payout method"
    },
                                            

The data section of this example response shows that gb_local_bank is a supported GB bank payout method type in the United Kingdom.

A real response usually lists many payout methods.

Finding Required Fields for the Payout Method Type

You need to find the required fields for the gb_local_bank 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 gb_local_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 GBP as the code for British Pounds, the sender's currency.
beneficiary_country	Enter GB as the code for the United Kingdom, the beneficiary's country.
payout_currency	Enter GBP as the code for British Pounds, 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 3000 as the amount received by the beneficiary.

Get Payout Required Fields Request

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

Request

// Request URL: GET https://sandboxapi.rapyd.net/v1/payout_methods/:pomt/required_fields?beneficiary_country=GB&beneficiary_entity_type=individual&payout_amount=3000&payout_currency=GBP&sender_country=GB&sender_currency=GBP&sender_entity_type=company
// Message body absent

.NET Core

using System;

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

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

                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/:pomt/required_fields?beneficiary_country=GB&beneficiary_entity_type=individual&payout_amount=3000&payout_currency=GBP&sender_country=GB&sender_currency=GBP&sender_entity_type=company'
    );

    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/:pomt/required_fields?beneficiary_country=GB&beneficiary_entity_type=individual&payout_amount=3000&payout_currency=GBP&sender_country=GB&sender_currency=GBP&sender_entity_type=company");
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

payout_method_type = 'gb_local_bank'
sender_country = 'GB'
sender_currency = 'GBP'
beneficiary_country = 'GB'
payout_currency = 'GBP'
sender_entity_type = 'company'
beneficiary_entity_type = 'individual'
payout_amount = 3000

path = f'/v1/payout_methods/:pomt/required_fields?beneficiary_country={beneficiary_country}&beneficiary_entity_type={beneficiary_entity_type}&' \
       f'amount={payout_amount}&payout_currency={payout_currency}&' \
       f'sender_country={sender_country}&sender_currency={sender_currency}&sender_entity_type={sender_entity_type}'
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": "7f6a6738-b0a2-469b-89d4-26f0cb70cd06"
},
"data": {
    "payout_method_type": "gb_local_bank",
    "sender_currency": "GBP",
    "sender_country": "*",
    "sender_entity_type": "company",
    "beneficiary_country": "GB",
    "payout_currency": "GBP",
    "beneficiary_entity_type": "individual",
    "is_cancelable": 0,
    "is_location_specific": 0,
    "is_expirable": 0,
    "minimum_expiration_seconds": null,
    "maximum_expiration_seconds": null,
    "is_online": null,
    "image": "/checkout/gb_local_bank.png",
    "status": 1,
    "beneficiary_required_fields": [
        {
            "name": "first_name",
            "regex": "^.{1,70}$",
            "is_required": true,
            "type": "string",
            "description": "Official first name of the bank account holder. First name and last name together should not exceed 70 characters"
        },
        {
            "name": "last_name",
            "regex": "^.{1,68}$",
            "is_required": false,
            "type": "string",
            "description": "Official last name of the bank account holder. First name and last name together should not exceed 70 characters"
        },
        {
            "name": "address",
            "regex": "^.{1,35}$",
            "is_required": true,
            "type": "string",
            "description": "Beneficiary street name ; building number"
        },
        {
            "name": "city",
            "regex": "^.{1,25}$",
            "is_required": true,
            "type": "string",
            "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
        },
        {
            "name": "state",
            "regex": "^.{1,15}$",
            "is_required": false,
            "type": "string",
            "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
        },
        {
            "name": "country",
            "regex": "^[A-Z]{2}$",
            "is_required": true,
            "type": "string",
            "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
        },
        {
            "name": "postcode",
            "regex": "^.{1,10}$",
            "is_required": false,
            "type": "string",
            "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
        },
        {
            "name": "account_number",
            "regex": "^.{1,34}$",
            "is_required": true,
            "type": "string"
        },
        {
            "name": "bic_swift",
            "regex": "^(.{8}|.{11})$",
            "is_required": true,
            "type": "string"
        }
    ],
    "sender_required_fields": [
        {
            "name": "company_name",
            "regex": "^.{1,35}$",
            "is_required": true,
            "type": "string"
        },
        {
            "name": "address",
            "regex": "^.{1,35}$",
            "is_required": true,
            "type": "string",
            "description": "street name ; building number"
        },
        {
            "name": "city",
            "regex": "^.{1,25}$",
            "is_required": true,
            "type": "string",
            "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
        },
        {
            "name": "state",
            "regex": "^.{1,15}$",
            "is_required": false,
            "type": "string",
            "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
        },
        {
            "name": "country",
            "regex": "^[A-Z]{2}$",
            "is_required": true,
            "type": "string",
            "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
        },
        {
            "name": "postcode",
            "regex": "^.{1,10}$",
            "is_required": false,
            "type": "string",
            "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
        },
        {
            "name": "purpose_code",
            "regex": "^(investment_income|salary|insurance_payments|computer_services|educational_services|payment_of_goods|payment_of_services|Inward_remittance)$",
            "is_required": false,
            "type": "string",
            "allowed_values": [
                "investment_income",
                "salary",
                "insurance_payments",
                "computer_services",
                "educational_services",
                "payment_of_goods",
                "payment_of_services",
                "Inward_remittance"
            ],
            "description": "Required only for sending to - China, India, South Korea, Philippines, Malaysia"
        }
    ],
    "payout_options": [
        {
            "name": "statement_descriptor",
            "regex": "[-a-zA-Z0-9?:().,'+ /]{1,35}",
            "is_required": true,
            "type": "string",
            "description": "Unstructured remittance information"
        }
    ],
    "minimum_amount": null,
    "maximum_amount": null,
    "batch_file_header": "payout_method_type,sender_currency,payout_currency,beneficiary.first_name,beneficiary.last_name,beneficiary.address,beneficiary.city,beneficiary.state,beneficiary.country,beneficiary.postcode,beneficiary.account_number,beneficiary.bic_swift,sender.company_name,sender.address,sender.city,sender.state,sender.country,sender.postcode,sender.purpose_code"
    }
}

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

You will use the required fields for the 'beneficiary' and 'sender' objects when you ask Rapyd to process the payout:

Beneficiary	Sender
`first_name`	`company_name`
`address`	`address`
`city`	`city`
`country`	`country`
`account_number`
`bic_swift`

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 employee is the beneficiary who receives the payout.

When your payroll manager requests a payout from the company's eWallet to an employee'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
beneficiary	Enter a 'beneficiary' object that has the following fields: `first_name` - Enter Henry `last_name` - Enter Tan `account_number` - Enter 77711020345678
beneficiary_country	Enter GB as the code for the United Kingdom, the beneficiary's country.
beneficiary_entity_type	Enter individual as the type of entity for the beneficiary.
description	Enter Salary payout via bank as the description of the payout transaction.
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_3d03be4b6ed60a217fb1faa7c01ae2ca, which is the company wallet ID we created in our sandbox.
payout_amount	Enter 3000 as the amount received by the beneficiary.
payout_currency	Enter GBP as the code for British Pounds, the currency received by the beneficiary.
payout_method_type	Enter gb_local_bank as the payout method type.
sender	Enter a 'sender' object that has the following fields: `company_name` - Enter Four Star Rideshare Service `purpose_code` - Enter salary
sender_currency	Enter GBP as the code for British Pounds, the sender's currency.
sender_entity_type	Enter company as the type of entity for the sender.
sender_country	Enter GB as the code for the United Kingdom, the sender's country.

Payouts for Extended Beneficiaries

Creating an extended beneficiary allows a merchant to collect additional information about their beneficiary before creating a payout. A beneficiary token ID is created, and is then passed in the Create Payout request.

For example, you could use an extended beneficiary for a payout if you are:

Making disbursements to independent content creators
Creating payouts for entertainment-based business platforms
Making a local payout to a supplier

See Create Extended Beneficiary for more information.

Create Payout Request

You ask Rapyd to process the manager's payout of 3,000 GBP (British Pounds) to the employee's GB bank account.

Request

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

// Message body: 
{
    "beneficiary": {
        "payment_type": "regular",
        "address": "45 Albert Road",
        "city": "Anytown",
        "country": "GB",
        "first_name": "Henry",
        "last_name": "Tan",
        "state": null,
        "postcode": "10101",
        "sort_code": "123456",
        "account_number": "77711020345678"
        
    },
    "beneficiary_country": "GB",
    "beneficiary_entity_type": "individual",
    "description": "des c15622888",
    "payout_method_type": "gb_local_bank",
    "ewallet": "ewallet_3d03be4b6ed60a217fb1faa7c01ae2ca",
    "metadata": {
        "merchant_defined": true
    },
    "payout_amount": "3000",
    "payout_currency": "GBP",
    
    "sender": {
        "first_name": "John",
        "last_name": "Doe",
        "identification_type": "work_permit",
        "identification_value": "asdasd123123",
        "phone_number": "19019019011",
        "occupation": "plumber",
        "source_of_income": "business",
        "date_of_birth": "11/12/1913",
        "address": "1 Main Street",
        "purpose_code": "investment_income",
        "beneficiary_relationship": "spouse",
        "city":"London",
        "state":null,
        "postcode":"1234"
    },
        "statement_descriptor":"GHY* Limited Access 800-123-4567",
    "sender_country": "GB",
    "sender_currency": "GBP",
    "sender_entity_type": "individual"
}

Create Payout Response

Let's take a look at the response.

Response

{
"status": {
    "error_code": "",
    "status": "SUCCESS",
    "message": "",
    "response_code": "",
    "operation_id": "0916d8d3-35e3-45f3-a56a-e3cc93262a38"
},
"data": {
    "id": "payout_92597636be2bcf8bb974e644db857ce3",
    "payout_type": "bank",
    "payout_method_type": "gb_local_bank",
    "amount": 3000,
    "payout_currency": "GBP",
    "sender_amount": 3000,
    "sender_currency": "GBP",
    "status": "Created",
    "sender_country": "GB",
    "sender": {
        "id": "sender_7d56509da5660fbd0366cf231f4a90fe",
        "last_name": "Doe",
        "first_name": "John",
        "country": "GB",
        "entity_type": "individual",
        "address": "1 Main Street",
        "name": "John Doe",
        "date_of_birth": "11/12/1913",
        "postcode": "1234",
        "city": "London",
        "phone_number": "19019019011",
        "currency": "GBP",
        "identification_type": "work_permit",
        "identification_value": "asdasd123123",
        "purpose_code": "investment_income",
        "beneficiary_relationship": "spouse",
        "source_of_income": "business",
        "occupation": "plumber"
    },
    "beneficiary_country": "GB",
    "beneficiary": {
        "id": "beneficiary_00fe9e62f04fd5f6cb3a248afb819e7e",
        "last_name": "Tan",
        "first_name": "Henry",
        "country": "GB",
        "entity_type": "individual",
        "address": "45 Albert Road",
        "name": "Henry Tan",
        "postcode": "10101",
        "city": "Anytown",
        "account_number": "77711020345678",
        "currency": "GBP",
        "sort_code": "123456",
        "payment_type": "regular"
    },
    "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_3d03be4b6ed60a217fb1faa7c01ae2ca",
            "amount": 3000,
            "percent": 100
        }
    ],
    "metadata": {
        "merchant_defined": true
    },
    "description": "des c15622888",
    "created_at": 1697240038,
    "payout_fees": null,
    "expiration": null,
    "paid_at": null,
    "identifier_type": null,
    "identifier_value": null,
    "error": null,
    "paid_amount": 0,
    "statement_descriptor": "GHY* Limited Access 800-123-4567",
    "gc_error_code": null,
    "estimated_time_of_arrival": "An estimated receipt time is not yet available for this payout method"
    }
}
                                            

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

The id of the 'payout' object is payout_92597636be2bcf8bb974e644db857ce3. Webhooks that relate to this payout refer to this ID.
The payout_type is bank.
Under sender:
- The id is sender_7d56509da5660fbd0366cf231f4a90fe .
- Fields of the 'sender' object are listed.
Under beneficiary:
- The id is beneficiary_00fe9e62f04fd5f6cb3a248afb819e7e .
- Fields of the 'beneficiary' object are listed.
The status is Created. This means that the 'payout' object was created successfully and the employee did not yet receive the payout funds.

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 employee's bank has accepted the transfer, 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

Local Bank Payout

Payout to Bank Account Workflow

Step 1: Requesting a Payout

Step 2: Processing the Payout

How a Local 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

Payouts for Extended Beneficiaries

Create Payout Request

Create Payout Response

Closing the Transaction

Simulating Payout Completion

Looking for More In-Depth Technical Information?

Search results