Mobile Checkout

Mobile Checkout APIs allow you to initiate Customer to Business (C2B) payments on a mobile subscriber's device. This allows for a smoother checkout experience, since the client will no longer need to remember the amount or an account number to complete the transaction.

Below is an illustration on how the mobile checkout service works

MOBILE CHECKOUT

Initiate a mobile checkout request by sending a HTTP POST request to the following endpoint:

Endpoints

Live:https://payments.africastalking.com/mobile/checkout/request
Sandbox:https://payments.sandbox.africastalking.com/mobile/checkout/request

Notifications

Once the mobile 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.

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
This is your Africa's Talking application username.
productName
String
Required
Your Africa's Talking Payment product to initiate this transaction.
providerChannel
String
Optional
The provider channel the payment will be initiated from e.g a paybill number. The provider channel must be mapped to your Africa's Talking payment product. If not specified, a default provider channel will be used.
phoneNumber
String
Required
Phone number - in international format - of the client that will complete this transaction.
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.3-digit ISO format currency code for the value of this transaction (e.g KES, UGX, USD, ...)
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 mobile checkout requests. It will be included in the notification we send once the client completes the mobile checkout request.
{
	"username": "MY-APPS-USERNAME",
	"productName": "My Online Store",
	"providerChannel": "345678",
	"phoneNumber": "+254711ABCXYZ",
	"currencyCode": "KES",
	"amount": 500.5,
	"metadata": {
		"shopId": "12345",
		"itemId": "abcde"
	}
}

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 and we are waiting for the subscriber to confirm the payment
  • 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 phone number 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 transactionId will be sent along with the payment notification.
providerChannel
String
Optional
The provider channel that was used to initiate this transaction

{
	"status": "PendingConfirmation",
	"description": "Waiting for user inout",
	"transactionId": "ATPid_SampleTxnId123",
	"providerChannel": "345678",
}

Initiate Mobile Checkout Sample code

The PHP code snippet below shows how to initiate a mobile checkout 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 phone number you want to send to in international format
$phoneNumber  = "+254711XXXYYY";

// Set The 3-Letter ISO currency code and the checkout amount
$currencyCode = "KES";
$amount       = 100.50;

// 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 {
    // Thats it, hit send and we'll take care of the rest.
    $result = $payments->mobileCheckout([
        "productName"  => $productName,
        "phoneNumber"  => $phoneNumber,
        "currencyCode" => $currencyCode,
        "amount"       => $amount,
        "metadata"     => $metadata
    ]);

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

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.response.CheckoutResponse;

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

public class TestMobileCheckout
{
    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 the phone number you want to send to in international format */
        String phoneNumber = "+25471xxxxxxx";

		/* Set The 3-Letter ISO currency code and the checkout amount */
		String currencyCode = "KES";
		float amount = 100;

		/*
			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 response = payment.mobileCheckout(
				productName, phoneNumber, currencyCode, amount, metadata);
			System.out.println(response.toString());

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

The Python code snippet below shows how to initiate a checkout request using our API

The code uses our Python SDK.

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

import africastalking

class MOBILE:
    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 phone number you want to send to in international format
        phoneNumber = "+25471XXXXXX"
        # Set The 3-Letter ISO currency code and the checkout amount
        currencyCode = "KES"
        amount = 100.50
		# 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"}
		# The provider channel the payment will be initiated from e.g a paybill number.
		provider_channel = '1122'
        try:
			# That's it hit send and we'll take care of the rest
            res = self.payment.mobile_checkout(productName, phoneNumber, currencyCode, amount, metadata)
            print (res)
        except Exception as e:
            print ("Received error response:%s" %str(e))

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

The Ruby code snippet below shows how to initiate a checkout validation request using our API

The code uses our Ruby SDK.

require 'AfricasTalking'

# Set your app credentials
username = "MyAppUsername"
apiKey   = "MyAppApiKey"

# 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  = "My Online Store"

# Set the phone number you want to send to in international format
phoneNumber  = "+254711XXXYYY"

# Set The 3-Letter ISO currency code and the checkout amount
currencyCode = "KES"
amount       = 100.50

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

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

The Nodejs code snippet below shows how to initiate a mobile checkout request using our Nodejs SDK.

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 initiateMobileCHeckout() {

    const options = {
        // Set the name of your Africa's Talking payment product
        productName: 'MyOnlineStore',
        // Set the phone number you want to send to in international format
        phoneNumber: '+254711XXXYYY',
        // Set the 3-Letter ISO currency code and the checkout amount
        currencyCode: 'KES',
        amount: 'Amount to be sent by customer',
        // 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: { "foo": "bar", "key": "value" }
    }

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

initiateMobileCHeckout();