Bank Checkout

Below is an illustration on how the bank checkout charge service works

BANK CHECKOUT CHARGE

Bank checkout APIs allow your application to collect money into your payment wallet by initiating transactions that deduct money from a customers bank account.

Please note: These APIs are currently only available in Nigeria.

Two endpoints are required in order for your application to complete a bank checkout request. These are:

  • Charge Request: Your application can initiate a transaction by sending a bank checkout charge request to our APIs. Once the request is accepted, the bank will send a One Time Password (OTP) to the user (either over SMS or on a device issued by the bank). Your application should provide the user a way to enter the OTP sent to them by the bank and finally send that to us using a bank checkout validate request to validate the transaction.
  • Validate Request: Your application can validate a transaction by sending us a bank checkout validate request. This request should send an OTP collected from a user and If the OTP matches with what we receive from the bank, the transaction will be completed successfully and the funds will be credited to your application's payment wallet.

Initiate a bank checkout by making aHTTP POST request to one of the following endpoint:

Endpoints

Live: https://payments.africastalking.com/bank/checkout/charge
Sandbox: https://payments.sandbox.africastalking.com/bank/checkout/charge

Notifications

Once the bank confirms or rejects the payment, our APIs will generate a payment notification and send it to the callback URL configured in your account for the product used to initiate the transaction. You can learn more about how to handle payment notifications in this section.

Supported Banks

Bank Checkout is currently available on the following banks:

Bank Name Bank Code
FCMB Nigeria
234001
Zenith Nigeria
234002
Access Nigeria
234003
Providus Nigeria
234007
Sterling Nigeria
234010

The following headers are required:

Parameter Description
apiKey
String
Africa's Talking application apiKey.
Content-Type
String
The requests content type. Must be application/json
Accept
String
The requests response type. Can be application/json or application/xml

The body of the request should be a JSON object containing the following fields:

Parameter Description
username
String
Required
Africa's Talking application username.
productName
String
Required
Africa's Talking Payment Product to initiate this transaction.
bankAccount
Map
Required
A Map containing details of the bank account to be charged in this transaction. bankAccount: Map Details of a bank account to be charged.
  • accountName: String Required Bank account name.
  • accountNumber: String Required Bank account number.
  • bankCode: Integer Required 6-Digit Integer code for the bank that we allocate.List of supported bank codes.
  • dateOfBirth: String Optional Date of birth of the account owner. Required for Zenith Nigeria.
currencyCode
String
Required
3-digit ISO format currency code for the value of this transaction (e.g KES, UGX, USD, ...)
amount
Decimal
Required
Amount in the provided currency that the client is expected to confirm.
narration
String
Required
Short description of the transaction that can be displayed on the clients statement.
metadata
Map<Str, Str>
Optional
A map of any metadata that you would like us to associate with the request. Use this field to send data that will map notifications to bank checkout charge requests. It will be included in the notification we send once the client completes the bank checkout request.
{
	"username": "MY-APPS-USERNAME",
	"productName": "My Online Store",
	"bankAccount": {
		"accountName": "Test Bank Account",
		"accountNumber": "1234567890",
		"bankCode": 234001,
		"daeOfBirth": "1990-01-10"
	},
	"currencyCode": "NGN",
	"amount": 500.50,
	"narration": "MTN Airtime Purchase",
	"metadata": {
		"requestId": "12345",
		"applicationId": "AppId123"
	}
}

API Response

The body of the response will be a JSON object containing the following fields:

Parameter Description
status
String
This corresponds to the status of the request. Possible values are:
  • PendingConfirmation - The request has been accepted. Your application should provide the user a way to enter the OTP sent to them by the bank and finally send that to us using a bank checkout validate request
  • InvalidRequest - The request could not be accepted as one of the fields was invalid. The description field will contain more information.
  • NotSupported - Checkout to the provided bank account is not supported.
  • Failed - The request failed for some other reason. The description filed will contain more information.
description
String
A detailed description of the request status.
transactionId
String
Optional
A unique id that our API generates for successful requests. This is the transactionId that should be sent along with the OTP to validate the payment.
{
	"status": "PendingValidation",
	"description": "Waiting for user input",
	"transactionId": "ATPid_SampleTxnId123"
}

Sample bank checkout code

The Ruby code snippet below shows how to initiate a checkout validation request using our API

The code uses our Ruby SDK.

require 'AfricasTalking'

# Set your app credentials
username = 'MyAppUsername'
apikey   = 'MyAppAPIKey'

# Initialize the SDK
AT=AfricasTalking::Initialize.new username, apikey

# Get the payments service
payments = AT.payments

# Set the name of your Africa's Talking payment product
productName = 'AT-productName'

# Set the details of the bank account to be charged
bankAccount = {
    'accountName' => 'Test Bank Account',
    'accountNumber' => '12345675433',
    'bankCode' => 234001,
    'dateOfBirth' => '2017-11-22'
}

# Set The 3-Letter ISO currency code and the checkout amount
currencyCode = 'KES'
amount       = 100.50

# Set a description of the transaction to be displayed on the clients statement
narration = 'This is a test transaction'

# Set any metadata that you would like to send along with this request. 
# This metadata will be included when we send back the final payment notification
metadata     = {
    'requestId' => '1234',
    'applicationId' => 'abcde'
}
options = {
    'productName' => productName,
    'currencyCode'=> currencyCode,
    'amount' => amount,
    'narration' => narration,
    'metadata' => metadata,
    'bankAccount' => bankAccount
}
begin
    # That's it, hit send and we'll take care of the rest
    transaction = payments.bankCheckoutCharge options
    puts transaction.to_yaml
    # Now you must validate the checkout by sending the transactionId generated from this 
    # request and an OTP you collected from the user. See Bank Checkout Validation
rescue Exception => ex
    puts "Encountered an error: " + ex.message
end
# DONE!

The PHP code snippet below shows how to initiate a bank checkout charge request.

The code uses our PHP SDK.

<?php
require 'vendor/autoload.php';
use AfricasTalking\SDK\AfricasTalking;

// Set your app credentials
$username   = "MyAppsUsername";
$apikey     = "MyAppAPIKey";

// Initialize the SDK
$AT         = new AfricasTalking($username, $apiKey);

// Get the payments service
$payments   = $AT->payments();

// Set the name of your Africa's Talking payment product
$productName = "My Online Store";

// Set the details of the bank account to be charged
$bankAccount = [
    "accountName"   => "Fela Kuti",
    "accountNumber" => "1234567890",
    "bankCode"      => payments::BANK["ACCESS_NG"]
];

// Set The 3-Letter ISO currency code and the checkout amount
$currencyCode       = "NGN";
$amount             = 10000.50;

// Set a description of the transaction to be displayed on the
// clients statement
$narration          = "Monthly service charge for My Online Store";

// Set any metadata that you would like to send along with this request.
// This metadata will be included when we send back the final payment notification
$metadata = [
    "agentId"   => "654",
    "productId" => "321"
];

try {
    // That's it, hit send and we'll take care of the rest
    $result = $payments->bankCheckoutCharge([
        "productName"  => $productName,
        "bankAccount"  => $bankAccount,
        "currencyCode" => $currencyCode,
        "amount"       => $amount,
        "narration"    => $narration,
        "metadata"     => $metadata
    ]);

    // Now you must validate the checkout by sending
    // the transactionId generated from this request and
    // an OTP you collect from the user.
    // See Bank Checkout Validate
    print_r($result);
} catch(Exception $e) {
    echo "Error: ".$e->getMessage();
}

The Java code snippet below shows how to initiate a checkout charge request using our API

The code uses our Java SDK.

/* Import SDK classes */
import com.africastalking.Callback;
import com.africastalking.AfricasTalking;
import com.africastalking.PaymentService;
import com.africastalking.payment.BankAccount;
import com.africastalking.payment.recipient.Bank;
import com.africastalking.payment.response.CheckoutResponse;

import java.util.HashMap;
import java.util.List;
import java.io.IOException;

public class TestBankCheckout
{
    public static void main(String[] args)
    {
		/* Set your app credentials */
		String USERNAME = "sandbox";
		String API_KEY = "";

		/* Initialize SDK */
		AfricasTalking.initialize(USERNAME, API_KEY);

		/* Get the payments service */
		PaymentService payment = AfricasTalking.getService(AfricasTalking.SERVICE_PAYMENT);

        /* Set the name of your Africa's Talking payment product */
        String productName = "SampleProduct";

		/* Set the details of the bank account to be charged */
        BankAccount account = new BankAccount("salama", "084802842", BankAccount.BankCode.FCMB_NG);

		/* Set The 3-Letter ISO currency code and the checkout amount */
		String currencyCode = "NGN";
        float amount = 7873;

		/* Set a description of the transaction to be displayed on the clients statement */
        String narration = "som narration";

		/*
			Set any metadata that you would like to send along with this request.
			This metadata will be included when we send back the final payment notification
		*/
		HashMap<String, String> metadata = new HashMap<String, String>();		
		metadata.put("someKey", "someValue");

		/* That's it, hit send and we'll take care of the rest */
		try {
			
			CheckoutResponse checkout = payment.bankCheckoutCharge(
				productName, currencyCode, amount, account, narration, metadata);
            System.out.println(checkout.toString());
            
			/*
				Now you must validate the checkout by sending the transactionId generated
				from this request and an OTP you collected from the user.
				See Bank Checkout Validation
			 */

		} catch(Exception ex) {
			ex.printStackTrace();
		}
   	}
}

The Python code snippet below shows how to initiate a bank checkout charge request using our API

The code uses our Python SDK.

# works with both python 2 and 3
from __future__ import print_function

import africastalking

class BANK:
    def __init__(self):
		# Set your app credentials
        self.username = "YOUR_USERNAME"
        self.api_key = "YOUR_API_KEY"
		# Initialize the SDK
        africastalking.initialize(self.username, self.api_key)
		# Get the payments service
        self.payment = africastalking.Payment

    def checkout(self):
        # Set the name of your Africa's Talking payment product
        productName = "ABC"
		# Set the details of the bank account to be charged
		account = {
            'accountNumber': '3234324235452345',
            'bankCode': self.payment.BANK['FCMB_NG'],
            'accountName': 'Fake Bob Naija',
            # Optional YYYY-MM-DD // required only for Zenith Nigeria
            #'dateOfBirth': '2000-01-01'
        }
        # Set The 3-Letter ISO currency code and the checkout amount
        currencyCode = "KES"
        # The checkout amount
        amount = 100.50
		# Set a description of the transaction to be displayed on the clients statement
        narration = 'Small Chops Checkout'
		# Set any metadata that you would like to send along with this request. This metadata will be included when we send back the final payment notification
		metadata     = {
    		'requestId' => '1234',
    		'applicationId' => 'abcde'
		}
        try:
			# That's it, hit send and we'll take care of the rest
            res = self.payment.bank_checkout(productName, currencyCode, amount, account, narration, metadata)
			# Now you must validate the checkout by sending the transactionId generated from this 
    		# request and an OTP you collected from the user. See Bank Checkout Validation
            print (res)
        except Exception as e:
            print ("Received error response:%s" %str(e))

if __name__ == '__main__':
    BANK().checkout()

The JavaScript code snippet below shows how to initiate a bank checkout charge request using our API

The code uses our Node SDK.

// Set your app credentials
const credentials = {
    apiKey: 'MyAppAPIkey',
    username: 'MyAppUsername'
}

// Initialize the SDK
const AfricasTalking = require('africastalking')(credentials);

// Get the payments service
const payments = AfricasTalking.PAYMENTS;


function initiateBankCheckout() {

    let options = {
        // Set the name of your Africa's Talking payment product
        productName: "myPaymentProductName",
        // Set the details of the bank account to be charged
        bankAccount: {
            accountName: "Test Bank Account",
            accountNumber: "1234567890",
            bankCode: payments.BANK.FCMB_NG
        },
        // Set The 3-Letter ISO currency code and the checkout amount
        currencyCode: "NGN",
        amount: "Amount to be transfered",
        // Set a description of the transaction to be displayed on the clients statement
        narration: "Payment for Airtime",
        // Set any metadata that you would like to send along with this request.
        // This metadata will be included when we send back the final payment notification
        metadata: { "foor": "bar", "key": "value" }
    };

    // That's it, hit send and we'll take care of the rest
    payments.bankCheckoutCharge(options)
        .then(response => {
            console.log(response);
        }).catch(error => {
            console.log(error);
        });
}

initiateBankCheckout()