Mobile Business To Business (B2B)

Below is an illustration on how the mobile B2B service works

MOBILE BUSINESS TO BUSINESS

Mobile Business To Business (B2B) APIs allow you to send payments to businesses e.g banks from your Payment Wallet. Initiate a mobile B2B request by making a HTTP POST request to one of the following endpoint:

Endpoints

Live:https://payments.africastalking.com/mobile/b2b/request
Sandbox:https://payments.sandbox.africastalking.com/mobile/b2b/request

Notifications

Once the mobile payment provider confirms or rejects the payment, our APIs will generate a payment notification and send it to the callback URL configured in your account for the product used to initiate this transaction. You can learn more about how to handle payment notifications in this section.

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
Africa's Talking Payment Product to initiate this transaction.
provider
String
Required
The provider that will be used to process the B2C request. Supported providers at the moment are:
  • Mpesa: Payments facilitated by Safaricom's M-PESA APIs
  • Athena: Payments facilitated by our Developer Sandbox.
Please note: This is not available on our production systems
transferType
String
Required
The payment provider that is facilitating this transaction. Supported providers at the moment are:
  • BusinessBuyGoods
  • BusinessPayBill
  • DisburseFundsToBusiness
  • BusinessToBusinessTransfer
currencyCode
String
Required
3-digit ISO format currency code for the value of this transaction (e.g KES, UGX, USD, ...)
amount
String
Required
Amount - in the provided currency - that the client is expected to confirm.
destinationChannel
String
Required
The name or number of the channel that will receive payment by the provider. e.g the Mobile Provider's PayBill or Buy Goods number that belongs to your organization.
destinationAccount
String
Required
The account name used by the business to receive money on the provided destinationChannel.
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 mobile b2b requests. It will be included in the notification we send once the client completes the mobile b2b request.

{
	"username": "MY-APPS-USERNAME",
	"productName": "My Online Store",
	"provider": "Mpesa",
	"transferType": "BusinessBuyGoods",
	"currencyCode": "KES",
	"amount": 100.00,
	"destinationChannel": "876543",
	"destinationAccount": "SUPPLIER-ACCOUNT-NAME",
	"metadata": {
		"shopId": "1234",
		"itemId": "abcdef"
	}
}

Mobile B2B Response

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

Parameter Description
status
String
Required
The status of the B2B transaction. Possible values are:
  • Queued The transaction has been accepted and queued for processing by the payment provider.
  • InvalidRequest We could not accept the request because one of the fields was invalid. The errorMessage field will contain a detailed description of the requests status.
  • NotSupported B2B requests to the provided phone number is not supported.
  • Failed Tthe B2B request failed for some other reason. The errorMessage field will contain a detailed description of the requests status.
transactionId
String
Optional
A unique id that our API generates for successful requests. This transactionId will be sent along with the payment notification.
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 credits NOT your payment wallet. The format of this string is: (3-digit Currency Code)(space)(Decimal Value) e.g KES 1.50
providerChannel
String
Optional
The provider channel which facilitated the payment.
errorMessage
String
Optional
A more descriptive error message for the status of this transaction.



{
	"status": "Queued",
	"transactionId": "ATPid_SampleTxnId123",
	"transactionFee": "KES 1.00",
	"providerChannel": "myPaymentProviderChannel"
}						    

Initiate mobile B2B Payment Sample code

The PHP code snippet below shows how to initiate a mobile b2b request.

The code uses our PHP SDK.

<?php
require 'vendor/autoload.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();

// Set the name of your Africa's Talking payment product
$productName        = "My Online Store";

// Set the payment provider
$provider           = payments::PROVIDER["ATHENA"];

// Set the destination channel and destination account
$destinationChannel = "businessDestinationChannel";
$destinationAccount = "businessDestinationAccount";

// Set the transfer type
$transferType       = payments::TRANSFER_TYPE["BUY_GOODS"];

// Set The 3-Letter ISO currency code and the checkout amount
$currencyCode       = "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 = [
    "agentId"   => "654",
    "productId" => "321"
];

try {
    // That's it, hit send and we'll take care of the rest. 
    $result = $payments->mobileB2B([
        "productName"        => $productName,
        "provider"           => $provider,
        "destinationChannel" => $destinationChannel,
        "destinationAccount" => $destinationAccount,
        "transferType"       => $transferType,
        "currencyCode"       => $currencyCode,
        "amount"             => $amount,
        "metadata"           => $metadata
    ]);

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

The Java code snippet below shows how to make Mobile B2B Payments 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.recipient.Business;
import com.africastalking.payment.response.B2BResponse;

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

public class TestMobileB2B
{
    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";

        Business recipient = new Business(

			/* Set the destination channel and destination account */
			"1212",
			"TestAccount",

			/* Set the transfer type */
			Business.TRANSFER_TYPE_PAYBILL,

			/* Set the payment provider */
			Business.PROVIDER_MPESA,
			
			/* Set The 3-Letter ISO currency code and the checkout amount */
			"KES",
			3322
		);

		/* That’s it, hit send and we'll take care of the rest. */
		try {
			B2BResponse response = payment.mobileB2B(productName, recipient);
			System.out.println(response.toString());
		} catch(Exception ex) {
			ex.printStackTrace();
		}
   	}
}

Make B2B Payment Using Our APIs in Python

The Python code snippet below shows how to make Mobile B2C Payments using our API.

The code uses our Python SDK.

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

import africastalking

class MOBILE:
    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 b2b(self):
        # Set the name of your Africa's Talking payment product
        productName = "ABC"
		# Set the payment provider
		provider = "myPaymentProvider"
		# Set the destination channel and destination account
		destination_channel = "partnerBusinessChannel"
		destination_account = "partnerBusinessChannelAccount"
		# Set the transfer type
		transfer_type = "BusinessToBusinessTransfer"
		# Set The 3-Letter ISO currency code and the checkout amount
		currency_code = "KES"
		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
		metadata = {
            'shopId' => "1234",
            'itemId' => "abcde"
           }

        business = {
			
			"provider": provider,
			"destinationChannel": destination_channel,
            "destinationAccount": destination_account,
			"transferType": transfer_type,
            "currencyCode": currency_code,
            "amount": amount,
            "metadata": metadata
        }
        try:
			# Thats it, hit send and we'll take care of the rest.
            res = self.payment.mobile_b2b(productName, business)
            print (res)
        except Exception as e:
            print ("Received error response:%s" %str(e))

if __name__ == '__main__':
    MOBILE().b2b()

The Ruby code snippet below shows how to initiate a checkout validation request using our API

The code uses our Ruby SDK.

require 'AfricasTalking'

# Set your app credentials
username = "MyAppUsername"
apikey   = "MyAppAPIKey"

# 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 payment provider
provider = "myPaymentProvider"

# Set the destination channel and destination account
destinationChannel = "partnerBusinessChannel"
destinationAccount = "partnerBusinessChannelAccount"

# Set the transfer type
transferType = "BusinessToBusinessTransfer"

# Set The 3-Letter ISO currency code and the checkout amount
currencyCode = "KES"
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
metadata = {
            'shopId' => "1234",
            'itemId' => "abcde"
           }
providerData = {
                'provider' => provider,
                'destinationChannel' => destinationChannel,
                'destinationAccount' => destinationAccount,
                'transferType' => transferType
               }
options = {
    'productName'  => productName,
    'providerData' => providerData,
    'currencyCode' => currencyCode,
    'amount'       => amount,
    'metadata'     => metadata
}
begin
    # Thats it, hit send and we'll take care of the rest. 
    transaction = payments.mobileB2B options
    puts transaction.to_yaml
rescue Exception => ex
    puts "Encountered an error: " + ex.message
end

The Nodejs code snippet below shows how to make Mobile B2B Payments request using our Nodejs SDK.

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

    const options = {
        // Set the name of your Africa's Talking payment product
        productName: "myPaymentProductName",
        // Set the payment provider
        provider: "myPaymentProvider",
        // Set the destination channel and destination account
        destinationChannel: "partnerBusinessChannel",
        destinationAccount: "partnerAccontName",
        // Set the transfer type
        transferType: "BusinessToBusinessTransfer",
        // Set The 3-Letter ISO currency code and the checkout amount
        currencyCode: "KES",
        amount: "Amount to be sent by customer",
        // 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", "key": "value" }
    }

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

initiateMobileB2B();