Bank Direct Debit

Withdraw funds from your customers' bank accounts

Bank direct debit is an authorized withdrawal from your customer's bank account. Direct debits are typically used in recurring transactions such as bill payments, memberships and subscriptions. Direct debit functionality is only available in select countries where the capability exists as part of a banking network. Popular direct debit capable schemes include:

  • Bacs in the UK
  • ACH in the US, Canada (ACHSS)
  • BECs in Australia
  • GIRO in Singapore

How it works

The direct debit process below explains how to:

  • add direct debit payments to your business workflow
  • create direct debit payment request
  • capture the payment response

🚧

For more information, see section 3.5 of Rapyd Network Rules. You must maintain a copy of this form in your records.

Find Available Payment Methods

Note: For illustration purposes, we will use:

* US ACH as our direct debit payment type.
* US and USD for country and currency in the sample codes.

Decide the payment methods you will accept so your customer can specify their payment methods on your payment page. To do that, use List Payment Methods by Country with the following parameters:

Query Parameter

Description

country

Enter US as the country code for the United States.

currency

Enter USD as the currency code for United States dollars.

List Payment Methods by Country Request

Request a list of all available payment methods in the US. Use List Payment Methods by Country with the following parameters:

// Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=US&currency=USD

// Message body absent
using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string country = "US";
                string currency = "USD";

                string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payment_methods/country?country={country}&currency={currency}");

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}
const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const result = await makeRequest('GET', '/v1/payment_methods/country?country=US&currency=USD');

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}
<?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

try {
    $object = make_request('get', '/v1/payment_methods/country?country=US&currency=USD');
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>
from pprint import pprint

from utilities import make_request

country = 'US'
currency = 'USD'
results = make_request(method='get',
                       path=f'/v1/payment_methods/country?country={country}&currency={currency}')
pprint(results)

List Payment Methods by Country Response

The response is generated below:

Note: See Payment Object for a description of the fields in the response.

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "90ebf1ec-9e40-49f6-9175-b3a764ab3cd0"
    },
    "data": [
        {
            "type": "us_ach_bank",
            "name": "Evolve Bank & Trust ",
            "category": "bank_transfer",
            "image": "https://iconslib.rapyd.net/checkout/us_ach_bank.png",
            "country": "us",
            "payment_flow_type": "bank_transfer",
            "currencies": [
                "USD"
            ],
            "status": 1,
            "is_cancelable": false,
            "payment_options": [],
            "is_expirable": false,
            "is_online": false,
            "minimum_expiration_seconds": null,
            "maximum_expiration_seconds": null
        }
    ]
}

The data section of this response shows that us_ach_bank is a supported payment method.

Note: A real response usually lists many payment methods.

Find Required Fields for the Payment Method

Identify the fields that your customer needs to complete for the payment method. To do that, use Get Payment Method Required Fields with the following parameter:

Path Parameter

Description

type

Enter us_ach_bank as the payment method type.

Get Payment Method Required Fields Request

Request a set of required fields for a us_ach_bank payment.

// Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/required_fields/us_ach_bank

// Message body absent
using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string type = "us_ach_bank";

                string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payment_methods/required_fields/{type}");

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}
const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const result = await makeRequest('GET', '/v1/payment_methods/required_fields/us_ach_bank');

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}
<?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

try {
    $object = make_request('get', '/v1/payment_methods/required_fields/us_ach_bank');
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>
from pprint import pprint

from utilities import make_request

payment_method = 'us_ach_bank'
results = make_request(method='get',
                       path=f'/v1/payment_methods/required_fields/{payment_method}')
pprint(results)

Get Payment Method Required Fields Response

The response is generated below:

Note: See Payment Object for a description of the fields in the response.

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "058bc78e-49aa-4370-b0b4-3635950173ac"
    },
    "data": {
        "type": "us_ach_bank",
        "fields": [
            {
                "name": "proof_of_authorization",
                "type": "boolean",
                "regex": "",
                "description": "",
                "is_required": true,
                "is_updatable": false
            },
            {
                "name": "first_name",
                "type": "string",
                "regex": "",
                "description": "",
                "is_required": false,
                "is_updatable": false
            },
            {
                "name": "last_name",
                "type": "string",
                "regex": "",
                "description": "",
                "is_required": false,
                "is_updatable": false
            },
            {
                "name": "company_name",
                "type": "string",
                "regex": "",
                "description": "",
                "is_required": false,
                "is_updatable": false
            },
            {
                "name": "routing_number",
                "type": "string",
                "regex": "^([0-9]){9,9}$",
                "description": "",
                "is_required": true,
                "is_updatable": false
            },
            {
                "name": "payment_purpose",
                "type": "string",
                "regex": "(PAYMENT|VENDOR PMT)",
                "description": "",
                "is_required": true,
                "is_updatable": false
            },
            {
                "name": "account_number",
                "type": "string",
                "regex": "^([0-9]){1,34}$",
                "description": "",
                "is_required": true,
                "is_updatable": false
            }
        ],
        "payment_method_options": [],
        "payment_options": [],
        "minimum_expiration_seconds": null,
        "maximum_expiration_seconds": null
    }
}

The data section of this response shows that the following fields are required for a us_ach_bank payment:

  • proof_of_authorization

🚧

Your customer must sign a proof of authorization form that complies with Rapyd's ACH network rules.
For more information, see section 3.5 of Rapyd Network Rules. You must maintain a copy of this form in your records.

  • routing_number
  • payment_purpose
  • account_number

The following fields are optional:

  • first_name
  • last_name
  • company_name

Create a Bank Transfer Payment

When your customer pays a loan on your website, create a request called Create Payment, using the following parameters, for Rapyd to process the ACH bank transfer payment:

Body Parameter

Description

amount

Enter 2100 as the payment amount.

currency

Enter USD as the currency code for US dollars.

payment_method

Enter an object with the following fields:
type - us_ach_bank
proof_of_authorization - true *. (Indicates
that your customer filled in a proof of
authorization form for the bank).
first_name - Jane
last_name - Doe
company_name - Acme
routing_number - 123UA34599
payment_purpose - Loan payment
account_number - USA_2340234-098-0908g

Create Payment Request

Request Rapyd to process your customer's payment (of US $2,100.00) as an ACH bank transfer.

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

// Message body: 
{
    "amount": 2100,
    "currency": "USD",
    "payment_method": {
        "type": "us_ach_bank",
        "fields": {
            "proof_of_authorization": true,
            "first_name": "Jane",
            "last_name": "Doe",
            "company_name": "Acme",
            "routing_number": "123UA34599",
            "payment_purpose": "Loan payment",
            "account_number": "USA_2340234-098-0908g"
        }
    }
}
using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var requestObj = new
                {
                    amount = 2100,
                    currency = "USD",
                    payment_method = new
                    {
                        type = "us_ach_bank",
                        fields = new
                        {
                            proof_of_authorization = true,
                            first_name = "Jane",
                            last_name = "Doe",
                            company_name = "Acme",
                            routing_number = "123UA34599",
                            payment_purpose = "Loan payment",
                            account_number = "USA_2340234-098-0908g",
                        }
                    }
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payments", request);

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}
const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const body = {
      amount: 2100,
      currency: 'USD',
      payment_method: {
        type: 'us_ach_bank',
        fields: {
          proof_of_authorization: true,
          first_name: 'Jane',
          last_name: 'Doe',
          company_name: 'Acme',
          routing_number: '123UA34599',
          payment_purpose: 'Loan payment',
          account_number: 'USA_2340234to098to0908g'
        }
      }
    };
    const result = await makeRequest('POST', '/v1/payments', body);

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}
from pprint import pprint

from utilities import make_request

payment_body = {
    "amount": 2100,
    "currency": "USD",
    "payment_method": {
        "type": "us_ach_bank",
        "fields": {
            "proof_of_authorization": True,
            "first_name": "Jane",
            "last_name": "Doe",
            "company_name": "Acme",
            "routing_number": "123UA34599",
            "payment_purpose": "Loan payment",
            "account_number": "USA_2340234-098-0908g"
        }
    }
}

create_payment_response = make_request(method='post',
                                       path='/v1/payments',
                                       body=payment_body)
pprint(create_payment_response)

Create Payment Response

The response is generated below:

Note: See Payment Object for a description of the fields in the response.

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "3ae269bc-11ff-477b-9f2a-ce69786876dc"
    },
    "data": {
        "id": "payment_a7ed3e41026614bc9e1d50981c099e07",
        "amount": 0,
        "original_amount": 2100,
        
//      ...          
          
        "currency_code": "USD",
        "country_code": "us",
        "status": "ACT",

        //      ...

        "customer_token": "cus_722c2234e6f83c5249b5376d743737cc",
        "payment_method": "other_1a06a5f97f4b0ff901d61f3ea704b296",

        //      ...

        "created_at": 1583408200,

        //      ...

        "paid": false,

        //      ...

        "payment_method_type": "us_ach_bank",
        "payment_method_type_category": "bank_transfer",

        //      ...

    }
}

The data section of this response shows:

  • The payment id is payment_a7ed3e41026614bc9e1d50981c099e07. When you run this in your own sandbox, you will get a different ID, which you will need for a later step.
  • The original_amount of the payment is 2100. You will need this value for a later step.
  • The currency_code is USD.
  • The status is ACT. This means that the payment process is active and awaiting completion. Payment Object lists possible values for status.

Close the Transaction

👍

Simulate Payment Completion

The sandbox does not directly simulate the action that completes a payment. You can simulate this action with the procedure described in Complete Payment. To do that, you will need the following values from the response you received when you ran 'Create Payment' in your sandbox:

  • payment id
  • code (in the textual_codes object)
  • original_amount.

When a payment is completed, Rapyd sends a webhook. Before you run 'Complete Payment', configure your system to receive webhooks with the procedure described in Setting a Webhook Endpoint for eWallet and POS API Sandboxes.

After you simulate the transfer of funds by your customer's bank, Rapyd sends you a webhook Webhook - Payment Completed to confirm that the payment was completed.

📘

Looking for more in-depth technical information?

Want to see the Rapyd API methods and objects that you'll use?
Visit the Rapyd API Reference Documentation for more technical details.


Updated about 19 hours ago


What's Next

Bank Transfers

Bank Direct Debit


Withdraw funds from your customers' bank accounts

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.