Payment Notifications

The Payment API sends a notification when a specific event happens. To receive these notifications you need to setup a callback URL depending on the type of notification.

Failed Notifications

Failed notifications (status code >= 400) will be retried every minute for 6 hours before giving up.

Types of payment notifications

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

Category Notification Point
BankCheckout Sent once the provided bank confirms or rejects the checkout request, or once the checkout request expires.
CardCheckout Sent once the card provider confirms or rejects the checkout request, or once the checkout request expires.
MobileCheckout Sent once the mobile subscriber confirms or rejects the checkout request, or once the checkout request expires.
MobileC2B Sent once funds are moved from the mobile subscriber's account to your payment wallet.
MobileB2C Sent 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 Stash with any transaction Fees.
MobileB2B Sent once funds are successfully moved from your payment wallet to the recipeints business 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 Stash with any transaction Fees.
BankTransfer Sent once funds are successfully moved from your payment wallet to the provided bank account 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 Stash with any transaction Fees.
WalletTransfer Sent once funds are successfully moved from your payment wallet to the target payment wallet.
UserStashTopup Sent once funds are successfully moved from your payment wallet to your Africa's Talking Stash.

Notification contents

The following parameters are sent with the notification to your callback URL.

Parameter Description
transactionId
String
A unique transactionId that we generate for every payment sent and received through our APIs.
category
String
The category of the payment. Possible values are:
  • BankCheckout: For Consumer-to-Business payments initiated by your application through our Bank Checkout APIs
  • CardCheckout: For Consumer-to-Business payments initiated by your application through our Card Checkout APIs
  • MobileCheckout: For Consumer-to-Business payments initiated by your application through our Mobile 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 application through our B2C APIs
  • MobileB2B: For Business-to-Business payments initiated by your application through our B2B APIs
  • BankTransfer: For Business-to-Business payments initiated by your application through our Bank Transfer APIs
  • WalletTransfer: For Wallet-to-Wallet payments initiated by your application through our Wallet Transfer APIs
  • UserStashTopup: For Wallet-to-application stash payments initiated by your application through our User Stash Topup APIs
provider
String
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
  • Segovia: This identifies payments facilitated by Segovia's APIs
  • Flutterwave: This identifies payments facilitated by Flutterwaves's APIs
  • Admin: This identifies payments facilitated by our administrative APIs
  • Athena: This identifies payments facilitated by our Developer Sandbox. This is obviously not available on our production systems.
providerRefId
String
Optional
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.
providerChannel
String
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.
clientAccount
String
Optional
The account name (if provided) used by a mobile subscriber to initiate this transaction. This value will only be present for Mobile C2B transactions.
productName
String
The Africa's Talking Payment Product that was used by your application to facilitate this transaction.
sourceType
String
  • 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
  • BankAccount: Indicates that the funds are being provided by a customer through their Bank Account. This is the case for Bank Checkout Transactions
  • Card: Indicates that the funds are being provided by a customer through their Debit or Credit Card. This is the case for Card Checkout 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
source
String
Unique identifier of the party that is providing the funds for this transaction. This value will contain either the phone number, bank account number or a card number of the customer who is sending funds to your application, or the special value PaymentWallet that identifies your Africa's Talking Payment Wallet.
destinationType
String
Unique identifier of the party that is receiving funds in this transaction (the Credit 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
  • BankAccount: Indicates that the funds are being provided by a customer through their Bank Account. This is the case for Bank Checkout Transactions
  • Card: Indicates that the funds are being provided by a customer through their Debit or Credit Card. This is the case for Card Checkout 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
destination
String
Unique identifier of the party that is receiving the funds for this transaction. This value will contain either a phone number, bank account number or a card number of the customer who is sending funds to your application, or the special value PaymentWallet that identifies your Africa's Talking Payment Wallet.
value
String
The value being exchanged in this transaction. The format of this string is: (3-digit Currency Code)(space)(Decimal Value) e.g KES 1.50
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 Stash NOT your payment wallet.
The format of this string is: (3-digit Currency Code)(space)(Decimal Value) e.g KES 1.50.
providerFee
Optional
The 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 Currency Code)(space)(Decimal Value) e.g KES 1.50. This value is only present in the case where a transaction was successful and the provider fee is being passed on to your application. Please Note: Tthis fee will also be deducted from the amount to be credited to your payment wallet.
status
String
The final status of this transaction. Possible values are:
  • Success
  • Failed
description
String
A detailed description of this transaction, including a more detailed failure reason in the case of failures.
requestMetadata
Map
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)
providerMetadata
Map
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.
transactionDate
String
Optional
The date and time (according to the payment provider) when a successful transaction was completed. This is only provided for successful transactions

Notification contents

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

{
	"requestMetadata": {
		"requestId": "12345",
		"applicationId": "AppId123"
	},
	"sourceType": "BankAccount",
	"source": "124567890",
	"provider": "Athena",
	"destinationType": "Wallet",
	"description": "Bank payment from Access Bank (Nigeria) [Mr. Test]: Payment has been completed successfully",
	"providerChannel": "Access Bank (Nigeria)",
	"direction": "Inbound",
	"transactionFee": "NGN 176.0000",
	"providerRefId": "dabe29f6-0464-445e-ad19-2cf4e3d55a0c",
	"providerMetadata": {},
	"origin": "ApiRequest",
	"status": "Success",
	"productName": "Nest Test",
	"category": "BankCheckout",
	"transactionDate": "2018-03-13 20:45:21",
	"destination": "PaymentWallet",
	"value": "NGN 9000.0000",
	"transactionId": "ATPid_de0b047c1bc76608599e9b1b2304535c"
}