Payment Card Checkout

Card Checkout APIs allow your application to collect money into your Payment Wallet by initiating transactions that deduct money from a customers Debit or Credit Card.

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

CARD CHECKOUT CHARGE

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

  • Charge Request: Your application can initiate a transaction by sending a card checkout charge request to our APIs. Once the request is accepted, the card provider will send a One Time Password (OTP) to the user (either over SMS or on a device issued by the card provider). Your application should provide the user a way to enter the OTP sent to them by the card provider and finally send that to us using a card checkout validate request to validate the transaction.
  • OTP Validation Request: Your application can validate a transaction by sending us a card checkout validate request. This request should send an OTP collected from a user and if the OTP matches with what we receive from the card provider, the transaction will be completed successfully and the funds will be credited to your applications payment wallet. The response to this request can optionally contain a Checkout Token. Checkout Tokens allow you to subsequently charge a users payment card without having to go through the card checkout validate process. This is useful for recurring card payments.

Initiate a card checkout charge request by sending a HTTP POST request to the following endpoints:

Please note: These APIs are currently only available in Nigeria on MasterCard and Verve cards.

Endpoints

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

Notifications

Once the card provider 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.

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
Your Africa's Talking Payment Product to initiate this transaction.
paymentCard
Map
Optional
A Map which contains details of the payment card to be charged in this transaction.
  • number: String Required Payment card number.
  • cvvNumber: Integer Required 3 or 4 digit payment card verification value.
  • expiryMonth: Integer Required Expiration month on the payment card.
  • expiryYear: Integer Required Expiration year on the payment card.
  • countryCode: String Required 2-Digit country code where the payment card was issued. Only "NG" is currently supported
  • authToken: String Require The payment cards ATM PIN.
Please note: You can EITHER provide a paymentCard or a checkoutToken if you have one.
checkoutToken
String
Optional
A token that has been generated by our APIs as as result of charging a users payment card in a previous transaction.
Please note: When using a checkoutToken, the paymentCard data should NOT be populated.
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 card checkout charge requests. It will be included in the notification we send once the client completes the card checkout request.
{
	"username": "MY-APPS-USERNAME",
	"productName": "My Online Store",
	"paymentCard": {
		"number": "123456789000",
		"cvvNumber": "654",
		"expiryMonth": 9,
		"expiryYear": 2020,
		"countryCode": "NG",
		"authToken": "12345",
	},
	"currencyCode": "NGN",
	"amount": 500.5,
	"narration": "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
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 payment card provider and finally send that to us using a card checkout validate request
  • Success - This means that the transaction has been completed and there is no further validation required. This can only happen in the case where you initiate a charge with a checkoutToken
  • 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 payment card 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 card charge request code

The php code snippet below shows how to initiate card 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 payment card to be charged
$paymentCard = [
    "number"      => "1234567890",
    "cvvNumber"   => 123,
    "expiryMonth" => 8,
    "expiryYear"  => 2019,
    "countryCode" => "NG",
    "authToken"   => "1234"
];

// If you already have a valid checkout token for the card user,
// as a result of a previous successful validation,
// you can charge the card by passing in the token
// instead of sending the full card information again.

// 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->cardCheckoutCharge([
        "productName"  => $productName,
        "paymentCard"  => $paymentCard,
        "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 Card Checkout Validate
    print_r($result);
} catch(Exception $e) {
    echo "Error: ".$e->getMessage();
}

The Ruby code snippet below shows how to initiate card checkout charge request using our API

The code uses our Ruby SDK.

require 'AfricasTalking'

# Set your app credentials
username = "MyApp_Username"
apikey   = "MyApp_APIKey"

# 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 payment card to be charged
paymentCard = {
  "number"=> "5105105105105100",
  "cvvNumber"=> 654,
  "expiryMonth"=> 9,
  "expiryYear"=> 2020,
  "countryCode"=> "NG",
  "authToken"=> "12345",
}

# 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"
}

# Token that has been generated by our APIs as as result of charging a user's Payment Card in a previous transaction. 
# When using a token, the paymentCard data should NOT be populated.
checkoutToken = nil

options = {
  'productName' => productName,
  'currencyCode'=> currencyCode,
  'amount' => amount,
  'narration' => narration,
  'checkoutToken' => checkoutToken,
  'metadata' => metadata,
  'paymentCard' => paymentCard
}
begin
    # That's it, hit send and we'll take care of the rest
    transaction = payments.cardCheckoutCharge options
    puts transaction.to_yaml
rescue Exception => ex
    puts "Encountered an error: " + ex.message
end

The Java code snippet below shows how to initiate a checkout 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.PaymentCard;
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)
    {
		/* Your app credentials */
		String USERNAME = "sandbox";
		String API_KEY = "";

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

		/* Get an instance of the PaymentService */
		PaymentService payment = AfricasTalking.getService(AfricasTalking.SERVICE_PAYMENT);

        /* Prepare checkout details */
        String productName = "SampleProduct";


		/*
			If you already have a valid checkout token for the card used as a result of a previous
			successful validation, you can charge the card by passing in the checkout token instead
			of sending the full card information again.
		*/
		// String checkoutToken = "some_token";

		/* or you can Set the details of the payment card to be charged */
        PaymentCard card = new PaymentCard("4223372036854775807", 1232, 10, 2022, "NG", "0022");
        
		/* Set The 3-Letter ISO currency code and the checkout amount */
		String currencyCode = "NGN";
		float amount = 4873;

		/* Set a description of the transaction to be displayed on the clients statement */
        String narration = "some 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.cardCheckoutCharge(
				productName, currencyCode, amount, card /* checkoutToken */, 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 collect from the user.
				See Card Checkout Validation
			 */
		} catch(Exception ex) {
			ex.printStackTrace();
		}
   	}
}

The Python code snippet below shows how to initiate card checkout charge using our API

The code uses our Python SDK.

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

import africastalking

class CARD:
    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 payment card to be charged
        card = {
            'number': '3234324235452345',
            'countryCode': 'NG',
            'cvvNumber': 3343,
            'expiryMonth': 3,
            'expiryYear': 2022,
            'authToken': '3322'
        }
        # If you already have a valid checkout token for the card user, as a result of a previous successful validation, 
        # you can charge the card by passing in the checkout token instead of sending the full card information again.
		checkout_token=None
        # Set The 3-Letter ISO currency code and the checkout amount
        currencyCode = "NGN"
        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.card_checkout(productName, currencyCode, amount, narration, card, checkout_token, metadata)
			# Now you must validate the checkout by sending the transactionId generated from this 
    		# request and an OTP you collected from the bank. See Card Checkout Validation.
            print (res)
        except Exception as e:
            print ("Received error response:%s" %str(e))

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

The JavaScript code snippet below shows how to initiate card checkout charge 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 initiateCardCheckout() {

    let options = {
        // Set the name of your Africa's Talking payment product
        productName: "myPaymentProductName",
        // Set The 3-Letter ISO currency code and the checkout amount
        currencyCode: "NGN",
        amount: 501,
        // Set a description of the transaction to be displayed on the clients statement
        narration: "Test card 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: { "foor": "bar" }
    };

    // Set the details of the card account to be charged
    const paymentCard = {
        number: "123456789012345",
        cvvNumber: 123,
        expiryMonth: 9,
        expiryYear: 2021,
        authToken: "1234",
        countryCode: "NG"
    }

    // OR

    // Set token generated by our APIs as as result of charging a user's Payment Card in a previous transaction
    const checkoutToken = "ATCdTkn_869e7b6126f0deb4b31eebe039a2e5f2d99be";

    // Use either the payment card or checkout token from previous transaction
    if (checkoutToken) {
        options.checkoutToken = checkoutToken;
    } else {
        options.paymentCard = paymentCard;
    }

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

initiateCardCheckout();

// Now you must validate the checkout by sending the transactionId generated from this request and an OTP you collected from the user.See Card Checkout Validation