Bank Transfer

Bank Tranfer APIs allow yout application to move money from your Payment Wallet to bank accounts.

Jump to:


How does it work? [Go Top]

We have implemented a RESTFul JSON API that allows your application to request funds transfers to bank accounts. Our API allows you to initiate multiple transactions in one request, all of which will be queued in our gateways for processing.

Once the payment provider confirms or rejects the payment request, our APIs will generate a payment notification and send it to the callback URL configured in your account. You can learn more about how to handle payment notifications in this section. Please note that a notification will be generated regardless of whether the transaction was successful or not.


Bank Transfer is currently available on the following banks:

Bank Name Bank Code
FCMB Nigeria 234001
Zenith Nigeria 234002
Access Nigeria 234003
GTBank Nigeria 234004
Ecobank Nigeria 234005
Diamond Nigeria 234006
Providus Nigeria 234007
Unity Nigeria 234008
Stanbic Nigeria 234009
Sterling Nigeria 234010
Parkway Nigeria 234011
Afribank Nigeria 234012
Enterprise Nigeria 234013
Fidelity Nigeria 234014
Heritage Nigeria 234015
Keystone Nigeria 234016
Skye Nigeria 234017
Stanchart Nigeria 234018
Union Nigeria 234019
UBA Nigeria 234020
Wema Nigeria 234021
First Nigeria 234022

How do I initiate a Bank Transfer request? [Go Top]

You can initiate a mobile Bank Tranfer request by sending a HTTP POST request to: https://payments.africastalking.com/bank/transfer.

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",
  "recipients": [
   {
     "bankAccount" : {
       "accountName"   : "Alyssa Hacker",
       "accountNumber" : "1234567890",
       "bankCode"      : 234001
     },
     "currencyCode": "NGN",
     "amount": 5000.10,
     "narration": "May Salary Payment",
     "metadata" : {
       "description" : "May Salary",
       "employeeId" : "123"
     }
   },
   {
     "bankAccount" : {
       "accountName"   : "Ben BitDiddle",
       "accountNumber" : "234567891",
       "bankCode"      : 234004
     }
     "currencyCode": "NGN",
     "amount": 10000.10,
     "narration": "May Salary Payment",
     "metadata" : {
       "description" : "May Salary",
       "employeeId" : "124"
     }
   }
}						
productName
String
Required
This value identifies the Africa's Talking Payment Product that should be used to initiate this transaction.
recipients
List
Required
This contains a list of Recipient elements, each of which corresponds to a B2C Transaction request. The format for each of these recipients is described in the table below.
Field Description
bankAccount
Complex
Required
Field 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.
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 receive.
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 transaction is complete.

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

r

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

Field Description Sample Response
errorMessage
String
Optional
This shows an optional error message if the ENTIRE request was rejected by the API. An example reason could be having too many requests, or having duplicate numbers in the request.It's only returned if an error was encountered
						    
{
  "entries": [
   {
    "accountNumber": "1234567890",
    "status": "Queued",
    "transactionId": "ATPid_SampleTxnId",
    "transactionFee", "NGN 50.00"
   },
   {
    "accountNumber": "234567891",
    "status": "Failed",
    "errorMessage", "Insufficient Credit"
   }
  ]
}				    
entries
List
Mandatory
This contains a list of Response entries, each of which corresponds to an account number that was received in the request. The fields are as shown here:
Field Description
accountNumber
String
Mandatory
This is the account number of the Bank Transfer recipient
status
String
Mandatory
This is the status of the request. Possible values are:
  • Queued: The transaction has been accepted and queued for processing by the payment provider. The result of this processing will be sent through the notification callback URL
  • InvalidRequest: This means that we could not accept the request because one of the fields was invalid. The errorMessage field will contain more information
  • NotSupported: This means that Bank Transfer requests to the provided bank account are not supported.
  • Failed: This means that the Bank Transfer request has failed for some other reason. The errorMessage field will have more details on the reason.
transactionId
String
Optional
This is a unique id that our API generates for a successful request. This is the transactionId that will be sent along with the final payment notification.
Not returned if entry had an error
transactionFee
String
Optional
This string contains the transaction fee charged by Africa's Talking for this transaction. The format of this string is: [3-digit currencyCode][space][Decimal Value]. An example would be: NGN 50.00 or KES 10.00. This value is only present in the case where a transaction was successful. Note that the transaction fee will be deducted from your Africa's Talking credits (not your payment wallet).
Not returned if entry had an error
errorMessage
String
Optional
This string contains a more descriptive error message for this transaction, if it was not successfully queued for processing by the API.
Only returned if entry had an error



Sample code [Go Top]

Our gateway classes contain simple helper functions which make integrating Bank Transfer Requests into your applications a total breeze.


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

Make Bank Transfers Using Our APIs in PHP

The PHP code snippet below shows how to make Bank Transfers from your Payment Wallet 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 = "MyAfricasTalkingUsername";
$apiKey   = "MyAfricasTalkingApiKey";

//Create an instance of our awesome gateway class and pass your credentials
$gateway = new AfricasTalkingGateway($username, $apiKey);

/*************************************************************************************
 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  = new AfricasTalkingGateway($username, $apiKey, "sandbox");
**************************************************************************************/

// Specify the name of your Africa's Talking payment product
$productName  = "Airtime Distribution";
// Specify bank accounts of recipients of the money
$recipient1   = array("bankAccount" => array("accountName"   => "Fela Kuti",
					     "accountNumber" => "1234567890",
					     "bankCode"      => 234004),
		      "currencyCode" => "NGN",
		      "amount"       => "100",
		      "narration"    => "May Salary",
		      "metadata"     => array("referenceId"  => "1235",
					      "officeBranch" => "201")
		      );

$recipient2   = array("bankAccount" => array("accountName"   => "Femi Kuti",
					     "accountNumber" => "234567891",
					     "bankCode"      => 234003),
		      "currencyCode" => "NGN",
		      "amount"       => "100",
		      "narration"    => "May Salary",
		      "metadata"     => array("referenceId"  => "1236",
					      "officeBranch" => "205")
		      );

// Put the recipients into a list
$recipients = array($recipient1, $recipient2);

try {
  // Initiate the transfer. If successful, you will get back a list of responses
  $responses = $gateway->bankPaymentTransfer($productName,
					     $recipients);
  
  foreach($responses as $response) {
    // Parse the responses and print them out
    echo "accountNumber=".$response->accountNumber;
    echo ";status=".$response->status;
    if ($response->status == "Queued") {
      echo ";transactionId=".$response->transactionId;
      echo ";transactionFee=".$response->transactionFee."\n";
    } else {
      echo ";errorMessage=".$response->errorMessage."\n";
    }
  }  
}
catch(AfricasTalkingGatewayException $e){
  echo "Received error response: ".$e->getMessage();
}

    

Send Bank Transfer Requests using Our APIs in Python

The Python code snippet below shows how to make Bank Transfer requests 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");
#**************************************************************************************

recipient1 = {
    'bankAccount'  : { 'accountName'   : 'Femi Kuti',
                       'accountNumber' : '11100223456',
                       'bankCode'      : 234003
                       },
    'currencyCode' : 'NGN',
    'amount'       : 100,
    'narration'    : 'May Salary',
    'metadata'     : { 'referenceId'  : '1235',
                       'officeBranch' : '201' }
    }

recipient2 = {
    'bankAccount'  : { 'accountName'   : 'Fela Kuti',
                       'accountNumber' : '22200223456',
                       'bankCode'      : 234004
                     },
    'currencyCode' : 'NGN',
    'amount'       : 50,
    'narration'    : 'May Salary',
    'metadata'     : { 'referenceId'  : '1236',
                       'officeBranch' : '201' }
    }

recipients = [recipient1, recipient2]

try:
    responses = gateway.bankPaymentTransfer(
        productName_  = 'Airtime Distribution',
        recipients_   = recipients
        )
    for response in responses:
	print "accountNumber=%s;status=%s;" % (response['accountNumber'],
                                               response['status'])
	if response['status'] == 'Queued':
	    print "transactionId=%s;transactionFee=%s;" % (response['transactionId'],
                                                           response['transactionFee'])
	else:
	    print "errorMessage=%s;" % response['errorMessage']

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