Rapyd Documentation and API

Bank Redirect

Rapyd makes it easy for your eCommerce website customers to pay for online purchases directly from a bank account.

Why Offer Bank Redirect? The customer may not have a credit card and there are no local direct debit capabilities. Bank Redirect is a highly preferred push payment method across Asia and LATAM because of security reasons.

How It Works

Find Available Payment Methods

Note: For illustration purposes, we will use MX (Mexico) and MXN (Mexican Peso) for country and currency in the sample codes below.

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 MX as the country code for Mexico.

currency

Enter MXN as the currency code for Mexican pesos.

List Payment Methods by Country request

Request a list of all available payment methods (in Mexican pesos). 

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

// Message body absent

using System;

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

                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=MX&currency=MXN');

    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=MX&currency=MXN');
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

from pprint import pprint

from utilities import make_request

country = 'MX'
currency = 'MXN'
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": "8065d391-d324-41cb-8b36-a7d97bd0ed6c"
    },
    "data": [{
            "type": "mx_bbva_bank",
            "name": "online bank payment BBVA mexico",
            "category": "bank_redirect",
            "image": "https://iconslib.rapyd.net/checkout/mx_bbva_bank.png",
            "country": "mx",
            "payment_flow_type": "redirect_url",
            "currencies": [
                "MXN"
            ],
            "status": 1,
            "is_cancelable": false,
            "payment_options": [],
            "is_expirable": false,
            "is_online": false,
            "minimum_expiration_seconds": null,
            "maximum_expiration_seconds": null
        }
    ]
}

The response shows that mx_bbva_bank is an acceptable payment method in the bank_redirect category.

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 mx_bbva_bank as the payment method type.

Get Payment Method Required Fields request

Request the set of required fields for a BBVA Bank payment.

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

// Message body absent

using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string type = "mx_bbva_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/mx_bbva_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/mx_bbva_bank');
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

from pprint import pprint

from utilities import make_request

payment_method = 'mx_bbva_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": "d4b9e9e7-0f9e-4a29-81b6-1e02c7d651af"
    },
    "data": {
        "type": "mx_bbva_bank",
        "fields": [],
        "payment_method_options": [],
        "payment_options": [],
        "minimum_expiration_seconds": null,
        "maximum_expiration_seconds": null
    }
}

The response shows that no fields are required for an mx_bbva_bank payment.

📘

For some payment method types in this category, 'fields' is mandatory and will need to be completed.
See sample code below where payment method type is in_icici_bank:

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

// Message body absent

The sample response is generated below where fields is populated with additional information required for processing this payment.

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "bdb942bd-6c91-4a1c-be66-d78d0c2053bd"
    },
    "data": {
        "type": "in_icici_bank",
        "fields": [
            {
                "name": "order_id",
                "type": "string",
                "regex": "",
                "description": "",
                "is_required": false,
                "is_updatable": false
            }
        ],
        "payment_method_options": [],
        "payment_options": [
            {
                "name": "customer",
                "type": "customer",
                "regex": "",
                "description": "make sure a customer was created with first_name, last_name and email ad phone_number",
                "is_required": false,
                "is_updatable": false
            }
        ],
        "minimum_expiration_seconds": null,
        "maximum_expiration_seconds": null
    }
}

Create the Payment

When your customer checks out on your website, use Create Payment with the following parameters to get Rapyd to process your customer's bank payment:

Body Parameter

Description

amount

Enter 200 as the payment amount.

currency

Enter MXN as the currency code.

complete_payment_url

Replace the https://success_example.net example with your real website URL where you want the bank to redirect the customer if the payment succeeds.

error_payment_url

Replace the https://error_example.net example with your real website URL where you want the bank to redirect the customer if the payment fails.

payment_method

Enter an object with the following field:
type - mx_bbva_bank

Create Payment request

Request Rapyd to process your customer's payment (200 MXN, in this case) as a redirected bank payment. 

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

// Message body:
{
    "amount": 200,
    "currency": "MXN",
    "complete_payment_url": "https://success_example.net",
    "error_payment_url": "https://error_example.net",
    "payment_method": {
        "type": "mx_bbva_bank"
    }
}

using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var requestObj = new
                {
                    amount = 200,
                    currency = "MXN",
                    complete_payment_url = "https:success_example.net",
                    error_payment_url = "https:error_example.net",
                    payment_method = new
                    {
                        type = "mx_bbva_bank",
                    }
                };

                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: 200,
      currency: 'MXN',
      complete_payment_url: 'https://success_example.net',
      error_payment_url: 'https://error_example.net',
      payment_method: {
        type: 'mx_bbva_bank'
      }
    };
    const result = await makeRequest('POST', '/v1/payments', body);

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

$body = [
    "amount" => "200",
    "currency" => "MXN",
    "complete_payment_url" => "https://success_example.net",
    "error_payment_url" => "https://error_example.net",
    "payment_method" => [
        "type" => "mx_bbva_bank"
    ]
];

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

from pprint import pprint

from utilities import make_request

payment_body = {
    "amount": 200,
    "currency": "MXN",
    "complete_payment_url": "https://success_example.net",
    "error_payment_url": "https://error_example.net",
    "payment_method": {
        "type": "mx_bbva_bank"
    }
}

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": "5b0e3b02-537d-4a5d-b70b-4b6a4fd35335"
    },
    "data": {
        "id": "payment_d562969cbe32f8ff175c98ad99a82d4e",
        "amount": 200,
        "original_amount": 200,
        "is_partial": false,
        "currency_code": "MXN",
        "country_code": "",
        "status": "ACT",

//      ...      

        "customer_token": "cus_5572507a5df016dcaf1cc1e0febfbe69",
        "payment_method": "other_c8af858b4d7cececb02a8755467c2a21",

//      ...      
      
        "captured": true,

//      ...      

        "redirect_url": "https://sandbox.rapyd.net/complete-bank-payment?token=payment_d562969cbe32f8ff175c98ad99a82d4e",
        "complete_payment_url": "https://success_example.net",
        "error_payment_url": "https://error_example.net",

//      ...      
 
        "created_at": "1549962206",

//      ...      
        "paid": false,

//      ...      

        "instructions": [
            {
                "name": "instructions",
                "steps": [
                    {
                        "step1": "You will be redirected to a bank payment page to complete the payment"
                    }
                ]
            }
        ],
          
//      ...      
 
        "payment_method_type_category": "bank_redirect"
    }}

}

The response shows:

  • The payment id is payment_d562969cbe32f8ff175c98ad99a82d4e. When you run this example in your own sandbox, you will get a different ID, which you will need for later steps.
  • The amount is 200.
  • The currency_code is MXN (Mexican pesos).
  • The status (under data) is ACT (active). This means that the payment process is active but not complete. Payment Object lists possible values for status.
  • These URLs are included:
    redirect_url - You redirect your customer to this one-time bank website URL to complete the payment.
    complete_payment_url and error_payment_url - Rapyd provides these URLs to the bank to redirect the customer back to your website depending on whether the purchase succeeded.
  • Instructions for your customer to complete the payment.
    Note: Your website shows your customer the instructions and redirects her to the bank website to
    complete the payment.

Receive Payment Confirmation

After your customer successfully makes a payment:

  1. The bank redirects your customer to the URL you provided for a successful payment.
  2. The bank informs Rapyd that the payment was completed successfully.
  3. Rapyd sends you a webhook with details of the completed transaction. See Webhook below.

👍

Simulating an Online Bank Payment

The sandbox does not directly simulate the action of the customer completing an online bank payment on the bank's website. You can simulate this action with the procedure described in Complete Payment. For this, you will need the payment ID that you generated in your sandbox.

Configure your system to receive webhooks with the procedure described in Setting a Webhook Endpoint for eWallet and POS API Sandboxes.

The webhook Webhook - Payment Completed is generated.

{
    "id": "wh_267680ccd8fd308b43da58fdd059cd2b",
    "type": "PAYMENT_COMPLETED”,

",
    "data": {
        "id": "payment_d562969cbe32f8ff175c98ad99a82d4e",
        "fee": 0,
        "paid": true,
        "order": null,
        "amount": 200,
        "status": "CLO",

//      ...      

        "captured": true,

//      ...      

        "created_at": "1549451666",

//      ...      

        "description": "bank_redirect",

//      ...      

        "redirect_url": "https://sandbox.rapyd.net/complete-bank-payment?token=payment_d562969cbe32f8ff175c98ad99a82d4e",

//      ...      


        "currency_code": "MXN",

//      ...      

        "customer_token": "cus_5572507a5df016dcaf1cc1e0febfbe69",
        "payment_method": "other_6095cc47e6db1390d170a7fe4a5da6f2",

//      ...      

        "original_amount": 200,

//      ...      
   
        "error_payment_url": "https://https://error_example.net",
        "payment_method_type": "",
        "complete_payment_url": "https://success_example.net",

//      ...      

        "payment_method_type_category": "bank_redirect"
    },

//      ...      

    "created_at": 1549451.726
}

The data section of the webhook contains the same type of information as the response to the Create Payment request, except that the status now is CLO (closed). This shows that the transaction is complete.

📘

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 5 days ago

What's Next

Cash Payments

Bank Redirect

Rapyd makes it easy for your eCommerce website customers to pay for online purchases directly from a bank account.

Suggested Edits are limited on API Reference Pages

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