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¤cy=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}¤cy={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¤cy=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¤cy=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}¤cy={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 isin_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: |
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
(underdata
) is ACT (active). This means that the payment process is active but not complete. Payment Object lists possible values forstatus
. - These URLs are included:
redirect_url
- You redirect your customer to this one-time bank website URL to complete the payment.
complete_payment_url
anderror_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:
- The bank redirects your customer to the URL you provided for a successful payment.
- The bank informs Rapyd that the payment was completed successfully.
- 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 |