Bank Account Checkout

Bank Account checkout APIs allow your application to collect money into your Payment Wallet by initiating an OTP-validated transaction that deducts money from a customer's bank account. These APIs are currently only available in Nigeria.

Jump to:


How does it work? [Go Top]

We have implemented 2 endpoints that are required in order for your application to get paid by a user from their Bank Account.

  • Charge Request: Your application can initiate a transaction by sending a Charge request to our APIs. Once the request is accepted, the bank will then send a One Time Password (OTP) to the user (either over SMS or on a device issued by the bank), which can then be used to confirm the transaction. Your application should therefore display a form entry page for collecting the OTP.
  • OTP Validation Request: Your application can validate the transaction by sending us the OTP that it collects from the user. If the OTP matches, the transaction will be completed successfully and the funds will be credited to your application's wallet.

Please note that once the bank confirms or rejects the payment, our APIs will ALSO 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.


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

How do I initiate a charge request? [Go Top]

You can initiate a Bank Charge request by sending a HTTP POST request to: https://payments.africastalking.com/bank/checkout/charge.

The following headers will be required for all requests

Header Description
apikey
String
Required
This is your Africa's Talking API Key

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

Field Description Sample Request
username
String
Required
This is your Africa's Talking username

{
  "username": "MyUsername"
  "productName": "My Online Store",
  "bankAccount": {
	  "accountName"   : "Test Bank Account",
	  "accountNumber" : "1234567890",
      "bankCode"      : 234001,
      "dateOfBirth"   : "2017-11-22"
   },
  "currencyCode": "KES",
  "amount": 500.5,
  "narration": "MTN Airtime Purchase",
  "metadata" : {
	  "requestId" : "1234568",
	  "applicationId" : "AppId123"
   }
}
productName
String
Required
This value identifies the Africa's Talking Payment Product that should be used to initiate this transaction.
bankAccount
Complex
Required
This is a complex type whose structure is described below. It contains the details of the bank account to be charged in this transaction.
Field Name Description
accountName
String
Optional
The name of the bank account.
accountNumber
String
Required
The account number.
bankCode
Integer
Required
An 6-Digit Integer Code for the bank that we allocate.
dateOfBirth
String
Required for Zenith Nigeria
Date of birth of the account owner.
currencyCode
String
Required
This is the 3-digit ISO format currency code for the value of this transaction (e.g NGN, USD, KES etc)
amount
Decimal
Required
This is the amount (in the provided currency) that the mobile subscriber is expected to confirm.
narration
String
Required
A short description of the transaction that can be displayed on the client's statement
metadata
String Map
Optional
This value contains a map of any metadata that you would like us to associate with this request. You can use this field to send data that will map notifications to checkout requests, since we will include it when we send notifications once the checkout is complete.

How does the API respond to a charge request? [Go Top]

The API responds to a charge request with a JSON response containing the fields shown below.

Field Description Sample Response
status
String
Mandatory
This corresponds to the status of this request. Possible values are:
  • PendingValidation: This means that the request has been accepted. Your application should display a form for the user to enter the OTP sent to them by the bank and send that to us using a Validation request.
  • InvalidRequest: This means that we could not accept the request because one of the fields was invalid. The description field will contain more information
  • NotSupported: Thie means that checkout to the provided bank account is not supported.
  • Failed: Thie means that the checkout request has failed for some other reason. The description field will have more details on the reason.

{
  "status": "PendingValidation",
  "description": "Waiting for user input",
  "transactionId": "ATPid_SampleTxnId123"
}
description
String
Mandatory
This provides a detailed description of the request status
transactionId
String
Optional
This is a unique id that our API generates for a request that is pending validation. It is the transactionId that should be sent along with the OTP to validate the payment.


Sample bank charge request code [Go Top

You need your AfricasTalking username and APIKey for any request to our API. If you don't have an APIKey, please click here to get one.
For sandbox APIKey, click here

Initiate Bank Account Checkout using PHP

The PHP code snippet below shows how to initiate a Bank Account checkout charge request using our API

The code uses our PHP gateway class: AfricasTalkingGateway.php [ Download]

Also, please ensure that you have the php_curl module enabled. To enable it uncomment the line: ;extension=php_curl.dll in php.ini and restart apache

<?php
require_once "AfricasTalkingGateway.php";

//Specify your credentials
$username = "my-apps-username";
$apikey   = "my-apps-apikey";
		
//Create an instance of our awesome gateway class and pass your credentials
$gateway = new AfricasTalkingGateway($username, $apikey);
// NOTE: If connecting to the sandbox, please add the sandbox flag to the constructor:
// $gateway = new AfricasTalkingGateway($username, $apiKey, "sandbox");

// Specify the name of your Africa's Talking payment product
$productName  = "Airtime Distribution";
// Specify the bank account of the customer checking out.
$bankAccount  = array(
		      "accountName"   => "Fela Kuti",
		      "accountNumber" => "1234567890",
		      "bankCode"      => 234004
		      );
// The 3-Letter ISO currency code for the checkout amount
$currencyCode = "NGN";
// The checkout amount
$amount       = 100;
// A narration describing the transaction on the user's bank statement
$narration    = "Payment for Airtime";
// 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     = array(
		      "requestId" => "MyRequestId1",
		      "productId" => "321"
		      );
try {
  // Initiate the checkout. If successful, you will get back a transactionId
  // that you can then use to validate the OTP that is sent to the user
  $transactionId = $gateway->bankPaymentCheckoutCharge($productName,
						       $bankAccount,
						       $currencyCode,
						       $amount,
						       $narration,
						       $metadata);
  echo "The transactionId is: ".$transactionId;
}
catch(AfricasTalkingGatewayException $e){
  echo "Received error response: ".$e->getMessage();
}

    

Initiate Bank Checkout using Python

The Python code snippet below shows how to initiate a Bank Account Checkout request using our API

The code uses our Python gateway class: AfricasTalkingGateway.py [ Download]

# Import the helper gateway class
from AfricasTalkingGateway import AfricasTalkingGateway, AfricasTalkingGatewayException

#Specify your credentials
username = "MyAfricasTalkingUsername"
apiKey   = "MyAfricasTalkingApiKey"

#Create an instance of our awesome gateway class and pass your credentials
gateway = AfricasTalkingGateway(username, apiKey, "sandbox")

#*************************************************************************************
#  NOTE: If connecting to the sandbox:
#
#  1. Use "sandbox" as the username
#  2. Use the apiKey generated from your sandbox application
#     https://account.africastalking.com/apps/sandbox/settings/key
#  3. Add the "sandbox" flag to the constructor
#
#  gateway = AfricasTalkingGateway(username, apiKey, "sandbox");
#**************************************************************************************

# Any gateway errors will be captured by our custom Exception class below, 
# so wrap the call in a try-catch block
try:
    # Send the request to the gateway. If successful, we will respond with
    # a transactionId that you can then use to validate the transaction
    transactionId = gateway.bankPaymentCheckoutCharge(
        productName_  = 'Airtime Distribution',
        currencyCode_ = 'NGN',
        amount_       = 100,
        narration_    = 'Airtime Purchase Request',
        bankAccount_  = {
            'accountName'   : 'Fela Kuti',
            'accountNumber' : '123456789',
            'bankCode'      : 234004
            },
        metadata_     = {
            'Reason' : 'To Test The Gateways'
            }
        )       
    print transactionId

except AfricasTalkingGatewayException, e:
    print 'Encountered an error while sending: %s' % str(e)