Bank Transfer

Below is an illustration on how the bank transfer service works

BANK TRANSFER

Bank Tranfer APIs allow you to move money from your Payment Wallet to bank accounts. Initiate a bank transfer request by making a HTTP POST request to one of the following endpoint:

Endpoints

Live: https://payments.africastalking.com/bank/transfer
Sandbox: https://payments.sandbox.africastalking.com/bank/transfer

Notifications

Once the payment provider 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 this transaction. You can learn more about how to handle payment notifications in this section

Supported Banks

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

Request Parameters

In addition to the standard request header, 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.
recipients
List
Required
A list of Recipient elements each corresponding to a bank transfer transaction request. Recipient is a Map of a recipient that will receive the bank transfer transaction.
  • bankAccount: Map Required Details of a bank account to receive the bank transfer payment.
  • accountName: String Optional 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 receive.
  • narration : 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 transfer requests. It will be included in the notification we send once the bank transfer request is completed.
{
	"username": "MY-APPS-USERNAME",
	"productName": "My Online Store",
	"recipients": [{
		"bankAccount": {
			"accountName": "John Doe",
			"accountNumber": "1234567890",
			"bankCode": 234002
		},
		"currencyCode": "NGN",
		"amount": 50000.00,
		"narration": "May Salary Payment",
		"metadata": {
			"description": "May Salary",
			"employeeId": "123"
		}
		}, {
		"bankAccount": {
			"accountName": "Jane Doe",
			"accountNumber": "1234567891",
			"bankCode": 234004
		},
		"currencyCode": "NGN",
		"amount": 50000.00,
		"narration": "May Salary Payment",
		"metadata": {
			"description": "May Salary",
			"employeeId": "124"
		}
	}]
}

Request Parameters

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

Parameter Description
errorMessage
String
Optional
Error message if the ENTIRE request was rejected by the API. e.g Having too many requests or having duplicate numbers in the request.
entries
List
A list of response Entry each corresponding to a recipient object in the bank transfer transaction request.
Entry is a Map containing details of a bank transfer transaction result.
  • accountNumber : String The account number of the bank transfer recipient.
  • status: String/Queued The transaction has been accepted and queued for processing by the payment provider.
    • InvalidRequest We could not accept the request because one of the fields was invalid. The errorMessage field will contain a detailed description of the request
    • NotSupported Bank transfer requests to the provided bank account is not supported.
    • Failed The request failed for some other reason. The errorMessage field will contain a detailed description of the request status.
  • transactionId: String/Optional A unique id that our API generates for successful requests. This transactionId will be sent along with the payment notification.
  • transactionFee: String/Optional The transaction fee charged by Africa's Talking for this transaction. Please note: The transaction fee will be deducted from your Africa's Talking credits NOT your payment wallet. The format of this string is: (3-digit Currency Code)(space)(Decimal Value) e.g NGN 50.00
  • errorMessage: String/Optional A more descriptive error message for the status of this transaction.

{
	"entries": [{
		"accountNumber": "1234567890",
		"status": "Queued",
		"transactionId": "ATPid_SampleTxnId",
		"transactionFee": "NGN 50.00"
		},
		{
		"accountNumber": "1234567891",
		"status": "Failed",
		"errorMessage": "Insufficient Credit"
	}]
}

Bank Transfers Sample code

The PHP code snippet below shows how to initiate a bank transfer 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 your bank transfer recipients
$recipients  = [[
    "accountName"   => "Fela Kuti",
    "accountNumber" => "1234567890",
    "bankCode"      => payments::BANK["ACCESS_NG"],
    "currencyCode"  => "NGN",
    "amount"        => 10000,
    "narration"     => "My Online Store service charge",
    "metadata"      => [
        "agentId"   => "654",
        "productId" => "321"
    ]
], [
    "accountName"   => "Ralph Kuti",
    "accountNumber" => "4567890123",
    "bankCode"      => payments::BANK["ZENITH_NG"],
    "currencyCode"  => "NGN",
    "amount"        => 20000,
    "narration"     => "My Online Store service charge",
    "metadata"      => [
        "agentId"   => "456",
        "productId" => "123"
    ]
]];

try {
    // That's it, hit send and we'll take care of the rest
    $results = $payments->bankTransfer([
        "productName" => $productName,
        "recipients"  => $recipients
    ]);

    print_r($results);
} catch(Exception $e) {
    echo "Error: ".$e->getMessage();
}

The Java code snippet below shows how to make a bank transfer 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 com.africastalking.payment.response.CheckoutValidateResponse;

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

public class TestBankTransfer
{
    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 your bank transfer recipients */
		List<Bank> banks = new ArrayList<Bank>();
        banks.add(
			new Bank(
				new BankAccount("Bob", "XXXXXXXX", BankAccount.BankCode.FCMB_NG),
				"NGN",
				XXXXX,
				"some narration",
				new HashMap<String, String>()				
			)
		);

		/* That's it, hit send and we'll take care of the rest */
		try {
			
			BankTransferResponse response = payment.bankTransfer(productName, banks);
            System.out.println(response.toString());

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

The Python code snippet below shows how to make Bank Transfer requests 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 bank_transfer(self):
        # Set the name of your Africa's Talking payment product
        productName = "ABC"
		# Set your bank transfer recipients
        recipients = [
            {
                "bankAccount": {
                    "accountNumber": "3234324235452345",
                    "bankCode": self.payment.BANK['FCMB_NG'],
                    "accountName": "Fake Bob Naija"
                },
                "currencyCode": "NGN",
                "amount": 332434,
                "narration": "Some description",
                "metadata": {}
            }
        ]
        try:
			# That's it, hit send and we'll take care of the rest
            res = self.payment.bank_transfer(productName, recipients)
            print (res)
        except Exception as e:
            print ("Received error response:%s" %str(e))

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

The Ruby code snippet below shows how to initiate a bank transfer using our API

The code uses our Ruby SDK.

require 'AfricasTalking'

# Specify your gem initialization credentials
username = "MyApp_Username"
apikey   = "MyApp_APIKey"

# Create a new instance of our awesome gem
AT=AfricasTalking::Initialize.new username, apikey
payments = AT.payments

# Specify the name of your Africas Talking payment product
productName  = "Airtime Distribution";

# Specify bank accounts of recipients of the money
recipients = Array.new
recipients[0]   = {
    "bankAccount" => {
        "accountName"   => "Fela Kuti",
        "accountNumber" => "1234567890",
        "bankCode"      => 234004
    },

    "currencyCode" => "NGN",
    "amount"       => "100",
    "narration"    => "May Salary",
    "metadata"     => {
        "referenceId"  => "1235",
        "officeBranch" => "201"
    }
}
recipients[1]   = {
    "bankAccount" => {
        "accountName"   => "Femi Kuti",
        "accountNumber" => "234567891",
        "bankCode"      => 234003
    },
    "currencyCode" => "NGN",
    "amount"       => "100",
    "narration"    => "May Salary",
    "metadata"     => {
        "referenceId"  => "1236",
        "officeBranch" => "205"
    }
}

options = {
    "productName" => productName,
    "recipients"  => recipients
}
begin
    # Initiate the checkout validate. If successful, you will get back a transactionId
    transaction = payments.bankTransfer options
    puts transaction.to_yaml
    transaction.entries.each {|entry| 
        puts entry.to_yaml
    }
rescue Exception => ex
    puts "Encountered an error: " + ex.message
end

The JavaScript code snippet below shows how to initiate a bank transfer using our API

The code uses our PHP 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 initiateBankTransfer() {

    // Set the name of your Africa's Talking payment product
    const productName = "myPaymentProductName";

    // Set your bank transfer recipients
    const recipients = [
        {
            bankAccount: {
                accountName: "Test Bank Account",
                accountNumber: "12345678910",
                bankCode: payments.BANK.FCMB_NG
            },
            currencyCode: "NGN",
            amount: "Amount to be transfered",
            narration: "Bank Transfer",
            metadata : { "foor": "bar"}
        },
        // ... More recipients
    ];

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

initiateBankTransfer();