Skip to main content

Documentation

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. During checkout your customers are redirected into a bank login flow, and once completed the customer will arrive back at a confirmation page on your site.

The bank transfer process below explains how to:

  • Add bank redirect payments to your business workflow.

  • Create a bank redirect payment request.

  • Capture the payment response.

Bank Redirect Checkout

The following screenshots represent a Bank Redirect checkout page workflow.

  1. Select your bank account.

  2. Click Place Your Order.

    6480837dafae3.png

  3. Complete the bank redirect.

    6480838068599.png

  4. Redirect to the payment success page.

    64808382e7d11.png

  5. Click Finish.

Online Bank Payment Workflow

Finding the specific bank redirect payment methods you'll accept and the corresponding required fields that customers fill out is described under How it Works.

Step 1: Processing the Payment
process-payment.jpg

  1. Customer checks out with an item and confirms a bank redirect payment on your page.

  2. Your website back end requests Rapyd to process the customer's payment, specifying the amount, currency, payment method for the customer's bank, and your payment success URL and error URL.

  3. Depending on whether the customer completes the payment with the bank successfully, the bank will redirect the customer to your website's success or error URL.

  4. Rapyd processes the transaction and responds with a unique bank URL to which you redirect the customer to complete the payment.

  5. The URL is valid only for this payment.

  6. Your website redirects the customer to the bank's URL.

Step 2: Completing the Payment
complete-payment.jpg

  1. On the bank website, the customer follows the bank's instructions to complete the payment.

  2. If the payment succeeds, the bank redirects the customer to the URL you specified for a successful payment. If the payment fails, the bank redirects the customer to the error URL you specified.

  3. Rapyd is notified by the bank that the payment is complete.

  4. Your website back end receives confirmation from Rapyd that the payment was completed.

Bank Redirect Message Sequences

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

Create a Bank Redirect Payment

create-payment-by-bank-redirect---production-environment.svg

Create a Bank Redirect Payment - Transaction Failed

create-payment-by-bank-redirect---transaction-failed.svg
How a Bank Redirect Works
Find Available Payment Methods

Decide the bank redirect 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:

Country and Currency Examples

MX (Mexico) and MXN (Mexican Pesos) is used for country and currency in the sample codes below.

Description of Query 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 MXN (Mexican Pesos).

    • Request

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

// Message body absent

    • .NET Core

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

    • JavaScript

      • 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

      • <?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";
}
?>

    • Python

      • 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)
Response

List Payment Methods by Country describes the fields in the response.

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

List Payment Methods Response

A real response 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:

Description of Path Parameters

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

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

// Message body absent

    • .NET Core

      • 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/{type}/required_fields");

                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/mx_bbva_bank/required_fields');

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

    • JavaScript

      • const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

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

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

    • PHP

      • <?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

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

    • Python

      • from pprint import pprint

from utilities import make_request

payment_method = 'mx_bbva_bank'
results = make_request(method='get',
                       path=f'/v1/payment_methods/{payment_method}/required_fields')
pprint(results)
Get Payment Method Required Fields Response

Get Payment Method Required Fields describes the fields in the response.

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

Payment Method Type

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

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

// Message body absent

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

    • Response

      •     "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:

Description of Body Parameters

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

      • // 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"
    }
}

    • .NET Core

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

    • JavaScript

      • 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

      • <?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";
}
?>

    • Python

      • 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)
pprint(results)
Create Payment Response

Create Payment describes the fields in the response.

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

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

Bank Redirect URL

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 Defining a Webhook Endpoint.

The webhook Webhook - Payment Completed is generated.

    • Webhook

      •    {
    "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 API Reference for more technical details.

In this section:

A transaction where funds are withdrawn directly from a bank account by electronic means.

In Rapyd, the sandbox environment provides most of the functionality of the production environment, without using real money. Interested persons can use the sandbox to explore Rapyd's product offering or to test software integrations with Rapyd's API.