Fetch Product Transactions

Fetch transactions of a particular payment product by sending a HTTP GET request to the following endpoint:

Endpoints

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

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.
productName
String
Required
The name of the payment product whose transactions you'd like to fetch.
pageNumber
String
Required
The number of the page you'd like to read results from. Please Note: This STARTS from 1 and NOT 0
count
String
Required
The number of transaction results you would like for this query.
startDate
String
Optional
Transaction start date you would like to consider in the format YYYY-MM-DD
endDate
String
Optional
Transaction end date you would like to consider in the format YYYY-MM-DD
category
String
Optional
Transaction category you would like to consider. Possible values are: BankCheckout, CardCheckout, MobileCheckout, MobileC2B, MobileB2C, MobileB2B, BankTransfer, BankWithdrawal, AdminWalletTopup, AdminWalletRefund, UserWalletTransfer, UserWalletTopup, UserStashTopup
provider
String
Optional
Transaction provider you would like to consider. Possible values are: Mpesa, Segovia, Flutterwave, Admin, Athena
status
String
Optional
Transaction status you would like to consider. Possible values are: Success, Failed
source
String
Optional
Transaction source you would like to consider. Possible values are: phoneNumber, BankAccount, Card, Wallet
destination
String
Optional
Transaction destinatiom you would like to consider. Possible values are: PhoneNumber, BankAccount, Card, Wallet
providerChannel
String
Optional
Transaction provider channel you would like to consider. This could, for example, be the Mobile Provider's Paybill or Buy Goods number that belongs to your organization.

Fetch Product Transactions 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:
  • Success: The request has been accepted.
  • Failed: The request has failed for some other reason; errorMessage field will have more info.
responses
List
A list of response entries whose structure is similar to the data objects on the find transaction request. Contains details of transactions that were found.
{
    "status": "Success",
    "responses": [{
        "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": "+254724XXXYYY",
        "value": "KES 2900.0000",
        "transactionId": "ATPid_b9379b671fee8ccf24b2c74f94da0ceb",
        "creationTime": "2018-05-12 18:46:12"
        }, {
        "requestMetadata": {},
        "sourceType": "Admin",
        "source": "AdminTopup",
        "provider": "Admin",
        "destinationType": "Wallet",
        "description": "Top up from paypal payment",
        "providerChannel": "AdminTopup",
        "providerMetadata": {},
        "status": "Success",
        "productName": "testing",
        "category": "AdminWalletTopup",
        "transactionDate": "2018-05-12 21:36:36",
        "destination": "PaymentWallet",
        "value": "KES 2900.0000",
        "transactionId": "ATPid_d1261ea6b5017494768ab42045796aa2",
        "creationTime": "2018-05-12 18:36:36"
    }]
}

Sample fetch product transactions request code

The PHP code snippet below shows how to send a fetch product transactions 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 fetchProductTransactions() {
    // Set the name of your Africa's Talking payment product
    $productName = "My Online Store";

    // Set the pageNumber and count you'll be fetching from
    $pageNumber  = 1;
    $count       = 50;

    // Set your fetch product transactions filters
    $filters     = [
        "pageNumber" => $pageNumber,
        "count"      => $count,
        "startDate"  => "2018-01-01",
        "endDate"    => "2018-06-25",
        "category"   => "MobileCheckout,BankCheckout",
        "status"     => "Failed"
    ];

    try {
        // Fetch the product transactions
        $transactions = $payments->fetchProductTransactions([
            "productName" => $productName,
            "filters"     => $filters
        ]);

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

fetchProductTransactions();

The JavaScript code snippet below shows how to fetch product transactions using our API

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

    let options = {
        // Set the name of your Africa's Talking payment product
        productName: "TestProduct",
        filters: {
            // Set the pageNumber and count you'll be fetching from
            pageNumber: "1",
            count: "100",
            // Set your other fetch product transaction filters
        }
    };

    // Fetch the product transactions
    payments.fetchProductTransactions(options)
        .then(resp => {
            console.log(resp.status);

            resp.responses.forEach(transaction => {
                console.log(transaction);
            });
        })
        .catch(error => {
            console.log(error);
        });
}

fetchMyTransactions();

The Java code snippet below shows how to fetch product transactions using our API

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 TestFetchProductTransactions
{
    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);

        /* Filter query */
        
        // The name of the payment product whose transactions you'd like to fetch.
        String productName = "TestProduct";

        HashMap<String, String> filters = new HashMap();

        // pageNumber start from 1 and NOT 0
        filters.put("pageNumber", "1");
        filters.put("count", "100");

        // Date format has to be YYYY-MM-DD
        filters.put("startDate", "2018-01-01");
        filters.put("endDate", "2018-12-31");

        // Possible categories are: 
        //      BankCheckout, CardCheckout, MobileCheckout,
        //      MobileC2B, MobileB2C, MobileB2B,
        //      BankTransfer, WalletTransfer, UserStashTopup
        filters.put("category", "UserStashTopup");

        // Providers include Mpesa, Segovia, Flutterwave, Admin, Athena
        filters.put("provider", "Athena");

        // Possible statuses are Success, Failed
        filters.put("status", "Success");

        // Possible sources are phoneNumber, BankAccount, Card, Wallet
        filters.put("source", "phoneNumber");

        // Possible destinations are PhoneNumber, BankAccount, Card, Wallet
        filters.put("destination", "PhoneNumber");

        // Channel to consider e.g. Paybill Number
        filters.put("providerChannel", "1212");
        

		/* And fetch the transactions (synchronously) */
		try {
            List<Transaction> transactions = payment.fetchProductTransactions(productName, filters);
            System.out.println("Fetched " + transactions.size() + " transactions");
			for (Transaction tx : transactions) {
                System.out.print(tx.transactionId);
                System.out.print(" : ");
                System.out.println(tx.toString());
            }
		} catch(Exception ex) {
			ex.printStackTrace();
		}
   	}
}

The Python code snippet below shows how to fetch product transactions using our API

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 product_transactions(self):
        # Set the name of your Africa's Talking payment product
        product_name = 'TestProduct'
		# Set your fetch wallet transactions filters
        filters = {
            # pageNumber start from 1 and NOT 0
            "pageNumber": "1",
            "count": "100",
            # Date format has to be YYYY-MM-DD
            "startDate": "2018-01-01",
            "endDate": "2018-12-31",
            # Possible categories are: BankCheckout, CardCheckout, MobileCheckout, MobileC2B, MobileB2C, MobileB2B, BankTransfer, WalletTransfer, UserStashTopup
            "category": "UserStashTopup",
            # Providers include Mpesa, Segovia, Flutterwave, Admin, Athena
            "provider": "Athena",
            # Possible statuses are Success, Failed
            "status": "Failed",
            # Possible sources are phoneNumber, BankAccount, Card, Wallet
            "source": "phoneNumber",
            # Possible destinations are PhoneNumber, BankAccount, Card, Wallet
            "destination": "PhoneNumber",
            # Channel to consider e.g. Paybill Number
            "providerChannel": "1212"
        }
        try:
			# Fetch the product transactions
            res = self.payment.product_transactions(product_name, filters)
            print (res)
        except Exception as e:
            print ("Received error response:%s" %str(e))

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

The Ruby code snippet below shows how to fetch product transactions using our API

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

# The name of the payment product whose transactions you'd like to fetch.
productName = "AT-productName"

# pageNumber start from 1 and NOT 0
pageNumber = 1
count = 5

# Date format has to be YYYY-MM-DD
startDate = '2016-06-01'
endDate = '2018-05-25'

# Possible categories are: 
# BankCheckout, CardCheckout, MobileCheckout, MobileC2B, MobileB2C, 
# MobileB2B, BankTransfer, WalletTransfer, UserStashTopup
category = 'UserWalletTransfer'

# Providers include Mpesa, Segovia, Flutterwave, Admin, Athena
provider = 'Admin'

# Possible statuses are Success, Failed
status = 'Success'

# Possible sources are phoneNumber, BankAccount, Card, Wallet
source = 'Wallet'

# Possible destinations are PhoneNumber, BankAccount, Card, Wallet
destination = 'BankAccount'

# Channel to consider e.g. Paybill Number
providerChannel = 'AdminTopup'

options = {
    'productName' => productName,
    'filters' => {
        'pageNumber' => pageNumber,
        'count' => count,
        'startDate' => startDate,
        'endDate' => endDate,
        'category' => category,
        'provider' => provider,
        'status' => status,
        'source' => source,
        'destination' => destination,
        'providerChannel' => providerChannel, 
    }
}
# And fetch the transactions
begin
    transaction = payments.fetchProductTransactions options
    puts transaction.to_yaml
    if transaction.status == 'Success'
        transaction.entries.each {|x|
            puts x.to_yaml
        }
    else
        puts 'status=' + transaction.status
    end
rescue Exception => ex
    puts "Encountered an error: " + ex.message
end