Payment Notifications

Notifications are at the heart of our Payment APIs. They allow you to implement simple endpoints that sit and wait for us to receive payment notifications from providers. Once we receive a payment notification, we will process it and send you a simple JSON requests notifying you about the completion of the transaction.

This means that you can implement a payment gateway using less than 5 lines of code (see the PHP example below)!

All payment notifications are logged and securely stored for easy access and interrogation through your Africa's Talking dashboard. We maintain real-time analytics that slice and dice your payments data in various dimensions to help you monitor the health of your business. All this is freely available with your Africa's Talking account.

Please note that in order to ensure that you do not miss any notifications, our APIs will retry failed notifications (status code >= 400) every minute for 6 hours before giving up.

Jump to:


When are notifications generated?[Go Top]

The point at which notifications are sent for various payment categories is shown below:

Payment Category Notification Point
Mobile Checkout We will send a final notification once the mobile subscriber confirms or rejects the checkout request, or once the checkout request expires.
Mobile C2B We will send a final notification once funds are moved from the mobile subscriber's account to your payment wallet.
Mobile B2C We will send a final notification once funds are successfully moved from your payment wallet to the mobile subscriber's account. If we are not able to complete the transaction, we will refund your payment wallet with the value of the transaction, and also refund your Africa's Talking account with any transaction Fees.

What is the content of each notification?[Go Top]

The POST request that we submit to your callback URL will contain a JSON-encoded object that has the following variables:
Variable Name Type Description Presence
transactionId String This is a unique transactionId that we generate for every payment sent and received through our APIs. Compulsory
category String This contains the category of the payment. Possible values are:
  • MobileCheckout: For Consumer to Business payments initiated by your application through our checkout APIs
  • MobileC2B: For Consumer to Business payments initiated by a mobile subscriber through their device (e.g using a paybill number)
  • MobileB2C: For Business to Consumer payments initiated by your apploication through our B2C APIs
Compulsory
provider String This contains the payment provider that facilitated this transaction. Supported providers at the moment are:
  • Mpesa: This identifies payments facilitated by Safaricom's M-PESA's APIs
  • Athena: This identifies payments facilitated by our Developer Sandbox. This is obviously not available on our production systems
Compulsory
providerRefId String This value contains the unique ID generated by the payment provider for this transaction (e.g the M-PESA transactionId). This value is only provided for successful transactions. Optional
providerChannelCode String This value contains the name or number of the channel that was used to facilitate this payment by the provider. This could, for example, be the Mobile Provider's Paybill or Buy Goods number that belongs to your organization. Compulsory
clientAccount String This value contains the account name (if provided) used by a mobile subscriber to initiate this transaction. This value will only be present for Mobile C2B transactions. Optional
productName String This value identifies the Africa's Talking Payment Product that was used by your application to facilitate this transaction. Compulsory
sourceType String This value identifies the type of the party that is providing the funds for this transaction (the Debit Party). Possible values are:
  • PhoneNumber: Indicates that the funds are being provided by a mobile subscriber through their mobile device. This is the case for Mobile Checkout and Mobile C2B Transactions
  • Wallet: Indicates that the funds are being provided by your Africa's Talking Wallet through one of your prodicts. This is the case for Mobile B2C Transactions
Compulsory
source String This value uniquely identifies the party that is providing the funds this transaction. This value will contain either the phone number of the mobile subscriber who is sending funds to your application, or the special value PaymentWallet that identifies your Africa's Talking Payment Wallet. Compulsory
destinationType String This value identifies the type of the party that is receiving funds in this transaction (the Credit Party). Possible values are:
  • PhoneNumber: Indicates that the funds are being sent to a mobile subscriber. This is the case for Mobile B2C Transactions
  • Wallet: Indicates that the funds are being sent to your Africa's Talking Wallet through one of your products. This is the case for Mobile Checkout and Mobile C2B Transactions
Compulsory
destination String This value uniquely identifies the party that is receiving funds in this transaction. This value will contain either the phone number of the mobile subscriber who is sending funds to your application, or the special value PaymentWallet that identifies your Africa's Talking Payment Wallet. Compulsory
value String This string contains the value being exchanged in this transaction. The format of this string is: [3-digit currencyCode][space][Decimal Value]. An example would be: KES 100.50 or UGX 3500.00. Compulsory
transactionFee String 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: KES 1.50 or UGX 35.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). Optional
providerFee String This string contains any fee charged by a payment provider to facilitate this transaction. An example would be the fee charged to the owner of a Paybill by a Mobile Money Provider in order to facilitate a C2B transaction. The format of this string is: [3-digit currencyCode][space][Decimal Value]. An example would be: KES 1.50 or UGX 35.00. This value is only present in the case where a transaction was successful and the provider fee is being passed on to your application. Note that this fee will also be deducted from the amount to be credited to your payment wallet. Optional
status String This value outlines the final status of this transaction. Possible values are:
  • Success
  • Failed
Compulsory
description String This value contains a detailed description of this transaction, including a more detailed failure reason in the case of failures. Compulsory
requestMetadata String Map This value contains a map of any metadata that was sent by your application when it initiated this transaction. You can use this field to reconcile transactions with your implementation by, for example, sending in KYC data or internal ids from your application that are linked to this transaction. The map will be empty for transactions that are not initiated by your application (such as Mobile C2B transactions). Compulsory
providerMetadata String Map This value contains a map of any additional data that we receive from a payment provider for a particulat transaction. This could contain, for example, KYC data associated with a C2B transaction or any additional regulatory information that is passed to our APIs by payment providers. The map will be empty in the case where a payment is not successful, or in the case where there is no additional data to provide. Compulsory
transactionDate String This value contains the date and time (according to the payment provider) when a successful transaction was completed. This is only provided for successful transactions Optional

What does a sample notification look like?[Go Top]

Our APIs will send notifications as a JSON object to the callback URL of your choice (as configured under your payment product). Below is a sample JSON request for a successful payment

{
  "transactionId": "ATPid_TestTransaction123",
  "category": "MobileCheckout",
  "provider": "Mpesa",
  "providerRefId": "MpesaID001",
  "providerChannelCode": "525900",
  "productName": "My Online Store",
  "sourceType": "PhoneNumber",
  "source": "+254711XYYZZZ",
  "destinationType" : "Wallet",
  "destination": "PaymentWallet",
  "value": "KES 1000",
  "transactionFee": "KES 1.5",
  "providerFee": "KES 5.5",
  "status": "Success",
  "description": "Payment confirmed by mobile subscriber",
  "requestMetadata" : {
      "shopId" : "1234",
      "itemId" : "abcdef"
   },
  "providerMetadata" : {
      "KYCName" : "TestCustomer",
      "KYCLocation" : "Nairobi"
   },
  "transactionDate": "2016-07-10T15:12:05+03"
}				    

How can I handle notifications in my application?[Go Top]

Let's dive into some code! Let us assume that you have configured your callback URL to point to: https://www.myTestOnlineShop.com/receivePayments.php. The snippet below shows the PHP code that you would implement at receivePayments.php in order to read in a JSON request from our APIs and extract some of the variables described above:
<?php
$data  = json_decode(file_get_contents('php://input'), true);
print_r($data);
// Process the data...
$category = $data["category"];
if ( $category == "MobileC2B" ) {
   // We have been paid by one of our customers!!
   $phoneNumber = $data["source"];
   $value       = $data["value"];
   $account     = $data["clientAccount"];
   // manipulate the data as required by your business logic
   // Perhaps send an SMS to confirm the payment using our APIs...
} else if ( $category == "MobileB2C" ) {

	.... some more logic ...

} else if ( $category == "MobileCheckout" ) {

	.... some more logic ...

} else {

	.... some more logic ...

}