Business Buy Goods
Pay from a business account directly into another merchant's Till number, store number, or head office, on your own behalf or a customer's.
Endpoint
https://sandbox.safaricom.co.ke/mpesa/b2b/v1/paymentrequestOverview
Pays a Till number, merchant store number, or merchant head office, moving money from your MMF/Working account into the recipient's Merchant account. Can be used to pay a merchant on behalf of a consumer/requester.
Shares its endpoint with Business Pay
Bill, B2C Account Top
Up, and Tax
Remittance. CommandID is what
distinguishes them; this one uses BusinessBuyGoods.
Request
{
"Initiator": "API_Usename",
"SecurityCredential": "FKXl/KPzT8hFOnozI+unz7mXDgTRbrlrZ+C1Vblxpbz7jliLAFa0E/…../uO4gzUkABQuCxAeq+0Hd0A==",
"Command ID": "BusinessBuyGoods",
"SenderIdentifierType": "4",
"RecieverIdentifierType": "4",
"Amount": "239",
"PartyA": "123456",
"PartyB": "000000",
"AccountReference": "353353",
"Requester": "254700000000",
"Remarks": "OK",
"QueueTimeOutURL": "https://mydomain.com/b2b/businessbuygoods/queue/",
"ResultURL": "https://mydomain.com/b2b/businessbuygoods/result/"
}Defect in the source material
Two issues carried over directly from Safaricom's own page for this API.
First, the sample body writes "Command ID" with a space, inconsistent with
the CommandID field name used in the parameter table on the same page (the
same defect documented on Business Pay
Bill). Second, that same parameter table's
CommandID row describes it as "For this API use BusinessPayBill only," a
description copy-pasted from the Business Pay Bill documentation rather than
updated for Buy Goods. The field this API actually accepts, based on the
sample value shown, is BusinessBuyGoods.
| Field | Description | Sample value |
|---|---|---|
CommandID | BusinessBuyGoods for this API (see defect note above regarding the source's own description of this field). | BusinessBuyGoods |
Initiator | API operator username, needs the appropriate Org Business Buy Goods API initiator role. | Username |
SecurityCredential | Encrypted initiator password. | (encrypted string) |
PartyA | Your short code, debited. | 123454 (5 to 6 digits) |
SenderIdentifierType | Only 4 is allowed. | 4 |
PartyB | Recipient Till/store short code, credited. | 000000 |
RecieverIdentifierType (sic) | Only 4 is allowed. | 4 |
Requester | Optional, consumer's mobile number if paying on their behalf. | 254700000000 |
Amount | Transaction amount. | 300 |
AccountReference | Up to 13 characters. | ACC#03929/4yu |
Remarks | Up to 100 characters. | Free text |
QueueTimeOutURL / ResultURL | Timeout and result callback URLs. | https://domain:port/path |
Occassion (sic) | Optional. | Free text |
Response
{
"OriginatorConversationID": "5118-111210482-1",
"ConversationID": "AG_20230420_2010759fd5662ef6d054",
"ResponseCode": "0",
"ResponseDescription": "Accept the service request successfully."
}Defect in the source material
Safaricom's response parameter table spells the first field
OriginatorConverstionID, the same typo documented on Business Pay Bill's
response.
Successful and unsuccessful result callbacks
Identical in shape to the callbacks documented on Business Pay Bill: a Result object with ResultType, ResultCode, ResultDesc, TransactionID, a ResultParameters.ResultParameter array (DebitAccountBalance, Amount, DebitPartyAffectedAccountBalance, TransCompletedTime, DebitPartyCharges, ReceiverPartyPublicName, Currency, InitiatorAccountCurrentBalance), and ReferenceData.ReferenceItem.
Defect in the source material
Safaricom's sample ReceiverPartyPublicName value here is the same malformed
one documented on Business Pay Bill: "000000– Biller Companty" (em dash,
misspelled "Company"), reproduced there and not repeated verbatim on this
page.
Testing and Go Live
Daraja Simulator: create a test app with the Business Buy Goods product attached.
Postman: token from the sandbox OAuth endpoint, then call the endpoint above.
Going live follows the Organization Portal & Go Live path, requiring the Business Buy Goods Org API Initiator role on the operator used as Initiator.