Payment Card Checkout

Payment Card Checkout APIs allow your application to collect money into your Payment Wallet by initiating transactions that deduct money from a customer's Debit or Credit Card.These APIs are currently only available in Nigeria on MasterCard and Verve cards.

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 Payment Card.

  • Charge Request: Your application can initiate a transaction by sending a 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 from the card issuer), 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 the response to this request can optionally contain a Checkout Token. Checkout Tokens allow you to subsequently charge the user's payment card without having to go through the OTP Validation process. This is useful for recurring payments

Please note that 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.

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

You can initiate a Payment Card Charge request by sending a HTTP POST request to: https://payments.africastalking.com/card/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",
"paymentCard": {
  "number"      : "123456789000",
  "countryCode" : "NG",
  "cvvNumber"   : "654",
  "expiryMonth" : 12,
  "expiryYear"  : 2019,
  "authToken"   : "2345",  
  },
"currencyCode": "NGN",
"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.
checkoutToken
String
Optional
This value contains a checkout token that has been generated by our APIs as as result of charging a user's Payment Card in a prevoius transaction. When using a token, the paymentCard data should NOT be populated
paymentCard
Complex
Optional
This is a complex type whose structure is described below. It contains the details of the Payment Card to be charged in this transaction. Please note that you can EITHER provider this or provider a checkoutToken if you have one.
Field Description
number
String
Required
The payment card number.
countryCode
String
Required
The 2-Digit countryCode where the card was issues (only NG is supported).
cvvNumber
Short
Required
The 3 or 4 digit Card Verification Value
expiryMonth
Int
Required
The expiration month on the card (e.g 1, 5, 12)
expiryYear
Int
Required
The expiration year on the card (e.g 2019)
authToken
String
Required
The card's ATM PIN
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 card provider and send that to us using a Validation 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: 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 card 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 card 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 Card Checkout using PHP

The PHP code snippet below shows how to initiate a Card Checkout request using our API s

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 the payment card values of the customer checking out.
$paymentCard  = array(
			  "number"      => "123456789012345",
		      "countryCode" => "NG",
		      "cvvNumber"   => 123,
		      "expiryMonth" => 9,
		      "expiryYear"  => 2019,
		      "authToken"   => "1234");

// 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->cardPaymentCheckoutCharge($productName,
						       $paymentCard,
						       $currencyCode,
						       $amount,
						       $narration,
						       $metadata);
  echo "The transactionId is: ".$transactionId;
}
catch(AfricasTalkingGatewayException $e){
  echo "Received error response: ".$e->getMessage();
}

    

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

<?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 a checkout token that you have previously received
$checkoutToken = "ATCdTkn_869e7b6126f0deb4b31eebe039a2e5f2d99be";

// 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->cardPaymentCheckoutChargeWithToken($productName,
								$checkoutToken,
								$currencyCode,
								$amount,
								$narration,
								$metadata);
  echo "The transactionId is: ".$transactionId;
}
catch(AfricasTalkingGatewayException $e){
  echo "Received error response: ".$e->getMessage();
}

    

Initiate Card Checkout using Python

The Python code snippet below shows how to send a checkout charge 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)

#*************************************************************************************
#  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);
#**************************************************************************************

paymentCard = {
    'number'      : '12344568901234',
    'countryCode' : 'NG',
    'cvvNumber'   : 205,
    'expiryMonth' : 9',
    'expiryYear'  : 2019,
    'authToken'   : '1234'
    }

# Any gateway errors will be captured by our custom Exception class below, 
# so wrap the call in a try-catch block
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.cardPaymentCheckoutCharge(
        productName_   = 'Airtime Distribution',
        paymentCard_   = paymentCard,
        currencyCode_  = 'NGN',
        amount_        = 100,
        narration_     = 'Airtime Purchase Request',
        metadata_      = {
            'Reason' : 'To Test The Gateways'
            }
        )
    print "The transactionId is %s" % transactionId

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

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

# Any gateway errors will be captured by our custom Exception class below, 
# so wrap the call in a try-catch block
try:
    gateway.cardPaymentCheckoutChargeWithToken(
        productName_   = 'Airtime Distribution',
        checkoutToken_ = 'ATCdTkn_ac1b0ce6c8ca6da4f50ab0d',
        currencyCode_  = 'NGN',
        amount_        = 100,
        narration_     = 'Airtime Purchase Request',
        metadata_      = {
            'Reason' : 'To Test The Gateways'
            }
        )
    print "The transactionId was successful"

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