Topup Stash

Topup stash APIs allow you to move money from a Payment Product to an Africa's Talking application stash. An application stash is the wallet that funds your service usage expences.

You can initiate a topup stash request by making a HTTP POST request to one of the following endpoints:

Endpoints

Live:https://payments.africastalking.com/topup/stash
Sandbox:https://payments.sandbox.africastalking.com/topup/stash

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
Your Africa's Talking Payment product to initiate 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 application will be topped up with.
metadata
Map<Str, Str>
Required
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 topup stash requests. It will be included in the notification we send once the topup stash request is completed.
{
    "username": "MY-APPS-USERNAME",
    "productName": "My Online Store",
    "currencyCode": "KES",
    "amount": 1500,
    "metadata": {
       "description": "May Charges"
    }
}

Topup-stash 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 and the funds have been transfered to the target payment product.
  • 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.
{
    "status": "Success",
    "description": "Topped up user stash. New Stash Balance: KES 1500.00",
    "transactionId": "ATPid_SampleTxnId123",
}

Topup stash request Sample code

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

    // Set The 3-Letter ISO currency code and the topup amount
    $currencyCode = "KES";
    $amount       = 10000.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 {
        // That's it hit send and we'll take care of the rest
        $result = $payments->topupStash([
            "productName"  => $productName,
            "currencyCode" => $currencyCode,
            "amount"       => $amount,
            "metadata"     => $metadata
        ]);

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

initiateTopupStash();

The JavaScript code snippet below shows how to move money from a Payment Product to an application stash 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 initiateStash() {

    let options = {
        // Set the name of your Africa's Talking payment product
        productName: "myPaymentProductName",
        // Set The 3-Letter ISO currency code and the topup amount
        currencyCode: "KES",
        amount: "Amount to be stashed",
        // 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: { "foor": "bar" }
    };

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

initiateStash();

The Java code snippet below shows how to o move money from a Payment Product to an application stash 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.TopupStashResponse;

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

public class TestTopupStash
{
    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 3-Letter ISO currency code and the topup 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 {
			TopupStashResponse response = payment.topupStash(productName, currencyCode, amount, metadata);
			System.out.println(response.toString());
		} catch(Exception ex) {
			ex.printStackTrace();
		}
   	}
}

The python code snippet below shows how to move money from a Payment Product to an application stash 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 top_up_stash(self):
        # Set the name of your Africa's Talking payment product
        product_name = "ABC"
        # Set The 3-Letter ISO currency code and the transfer amount
        currency_code = "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 = {
            'someKey': 'someValue',
        }
        try:
			# That's it hit send and we'll take care of the rest
            res = self.payment.topup_stash(product_name, currency_code, amount, metadata)
            print (res)
        except Exception as e:
            print ("Received error response:%s" %str(e))

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

The Ruby code snippet below shows how to move money from a Payment Product to an application stash using our API.

The code uses our Ruby SDK.

require 'AfricasTalking'

# Set your app credentials
username = "MyApp_Username"
apikey   = "MyApp_APIKey"

# 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 = "AT-productName"

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

# 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     = {
    "description" => "May Rent"
}

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