Query Find Transaction

Find a particular payment transaction by sending a HTTP GET request to the following endpoint:

Endpoints

Live: https://payments.africastalking.com/query/transaction/find
Sandbox: https://payments.sandbox.africastalking.com/query/transaction/find

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.
transactionId
String
Required
ID of the transaction you would like to find.

Find Transaction Response

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

Parameter Description
status
String
This corresponds to the status of the request. Possible values are
  • Success - The request has been accepted.
  • Failed - The request has failed for some other reason; errorMessage field will have more info.
data
Map
Map containing details of the transaction that was found.
data is a Map with details of transaction being queried
  • requestMetadata: Map - Any metadata that was sent by your application when it initiated this transaction.
  • sourceType: String - The type of party that is providing 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.
    • BankAccount - Indicates that the funds are being provided by a customer through their Bank Account.
    • Card - Indicates that the funds are being provided by a customer through their Debit or Credit Card.
    • Wallet - Indicates that the funds are being provided by your Africa's Talking Wallet through one of your products.
  • source: String - This value uniquely identifies 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.
  • provider: String - 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.
  • 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 provided by a mobile subscriber through their mobile device.
    • BankAccount - Indicates that the funds are being provided by a customer through their Bank Account.
    • Card - Indicates that the funds are being provided by a customer through their Debit or Credit Card.
    • Wallet - Indicates that the funds are being provided by your Africa's Talking Wallet through one of your products.
  • description: String - This value contains a detailed description of this transaction, including a more detailed failure reason in the case of failures.
  • providerChannel: String - This value contains the name or number of the channel that was used to facilitate this payment by the provider.
  • 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.
  • providerRefId: String - This value contains the unique ID generated by the payment provider for this transaction (e.g the M-PESA transactionId).
  • providerMetadata: Map - This value contains a map of any additional data that we receive from a payment provider for a particular transaction.
  • status: String - This value outlines the final status of this transaction. Possible values are: Success Failed
  • productName: String - This value identifies the Africa's Talking Payment Product that was used by your application to facilitate this transaction.
  • category: String - This contains 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
  • 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
  • destination: String - This value uniquely identifies the party that is receiving the funds for this transaction. This value will contain either a phonen umber, 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 - This string contains 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
  • transactionId: String - This is a unique transactionId that we generate for every payment sent and received through our APIs.
  • creationTime: String - This value contains the date and time when a transaction was accepted by our APIs.
{
    "status":"Success",
    "data":{
    "requestMetadata":{
        "reason":"Testing things..."
    },
    "sourceType":"Wallet",
    "source":"PaymentWallet",
    "provider":"Mpesa",
    "destinationType":"PhoneNumber",
    "description":"The service request is processed successfully.",
    "providerChannel":"824879",
    "transactionFee":"KES 1.0000",
    "providerRefId":"SAMPLE_MPESA_CODE",
    "providerMetadata":{
        "recipientIsRegistered":"true",
        "recipientName":"254724XXXYYY - John Doe"
    },
    "status":"Success",
    "productName":"testing",
    "category":"MobileB2C",
    "transactionDate":"12.05.2018 21:46:13",
    "destination":"+254708663158",
    "value":"KES 2900.0000",
    "transactionId":"ATPid_b9379b671fee8ccf24b2c74f94da0ceb",
    "creationTime":"2018-05-12 18:46:12"
    }
}

Sample find transactions request code

The PHP code snippet below shows how to send a find transaction request.

The code uses our PHP SDK.

<?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();

function findTransaction() {
    // Set the id of the transaction you want to find
    $transactionId = "ATSampleTxId001";

    try {
        // Find the transaction
        $transaction = $payments->findTransaction([
            "transactionId" => $transactionId
        ]);

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

findTransaction();

The JavaScript code snippet below shows how to find a transaction of a particular payment product.

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

    let options = {
        // Set the id of the transaction you want to find
        transactionId: "ATPid_c7a49b14ae024c3c1af2cfc8645542d4"
    };

    // Find the transaction
    payments.findTransaction(options)
        .then( response => {
            console.log(response);
        })
        .catch( error => {
            console.log(error);
        });
}

findMyTransaction();

The Java code snippet below shows how to find a transaction of a particular payment product.

The code uses our Java SDK.

/* Import SDK classes */
import com.africastalking.Callback;
import com.africastalking.PaymentService;
import com.africastalking.payment.Transaction;
import com.africastalking.AfricasTalking;

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

public class TestFindTransaction
{
    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);

        /* Transaction to find */
        String transactionId = "ATPid_e95ca121bb7d02cade86868193b91de4";
        

		/* And find the transaction (synchronously) */
		try {
            Transaction transaction = payment.findTransaction(transactionId);
            System.out.println(transaction.toString());
		} catch(Exception ex) {
			ex.printStackTrace();
		}
   	}
}

The Python code snippet below shows how to find a transaction of a particular payment product.

The code uses our Python SDK.

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

import africastalking

class PAYMENTS:
    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 find_transaction(self):
        # Set transaction id to find
        transaction_id = 'ATPid_e95ca121bb7d02cade86868193b91de4'
        try:
			# That's it, hit send and we'll take care of the rest
            res = self.payment.find_transaction(transaction_id)
            print (res)
        except Exception as e:
            print ("Received error response:%s" %str(e))

if __name__ == '__main__':
    PAYMENTS().find_transaction()

The Ruby code snippet below shows how to find a transaction of a particular payment product.

The code uses our Ruby SDK.

require 'AfricasTalking'

# Your app credentials
username = "MyApp_Username"
apikey   = "MyApp_APIKey"

# Initialize SDK
AT=AfricasTalking::Initialize.new username, apikey

# Get an instance of the PaymentService
payments = AT.payments

# Transaction to find
transactionId = "ATPid_7g016aae0c10478fc8427950bdb0fdba"

options = {
    'transactionId' => transactionId
}
# And find the transaction
begin
    transaction = payments.findTransaction options
    puts transaction.to_yaml
rescue Exception => ex
    puts "Encountered an error: " + ex.message
end