Collect from Mobile Money

Use this endpoint to send a USSD push request to a mobile subscriber to receive payment

Send a USSD Push request

POST https://sandbox.temboplus.com/tembo/v1/collection

Collect money from a mobile subscriber through a USSD push request

Headers

Name	Type	Description
x-account-id*	string	Partner account id
x-secret-key*	string	Partner secret key
x-request-id*	string	A unique id identifying this request

Request Body

Name	Type	Description
msisdn*	string	The MSISDN of the mobile subscriber in the format 255XXX123456 to which the USSD push request should be sent
channel*	string	The MNO to of the mobile subscriber. Supported values are: TZ-TIGO-C2B, TZ-AIRTEL-C2B
amount*	number	The amount to be collected
narration*	string	Narration for this transfer
transactionRef*	string	Your system reference that should be associated with this transaction
transactionDate*	string	The date of the transaction in the format YYYY-MM-DD HH:mm:ss
callbackUrl*	string	The web hook callback URL to be called with the current transaction update

200 Success

// If the request is rejected for any reason, the 'statusCode' will be set to 'PAYMENT_REJECTED.'
// In the event of an error, the 'statusCode' will be set to 'GENERIC_ERROR.'
{
  "statusCode": "PENDING_ACK",
  "transactionRef": "20f807fe-3ee8-4525-8aff-ccb95de38250",
  "transactionId": "X50jcLD-U"
}

401 Invalid Credentials

{
    "statusCode": 401,
    "reason": "INVALID_CREDENTIALS"
}    

cURL

curl --request POST \
  --url https://sandbox.temboplus.com/tembo/v1/collection \
  --header 'content-type: application/json' \
  --header 'x-account-id: ff6IfxxVceIMM6oFAc9Zig' \
  --header 'x-secret-key: HYX5X4is3a4bnJJo4lXM936bFD6B8iMeAtXijNvHXMI==' \
  --header 'x-request-id: 546d7a200cd8cb45d8ac'
  --data '{
	"channel": "TZ-AIRTEL-C2B",
	"msisdn": "255778342299",
	"amount": 1000,
	"transactionRef": "ARC5847AF",
	"narration": "Inbound trx from 0713809050",
	"transactionDate": "2023-08-22 16:15:33",
	"callbackUrl": "https://example.com/my-callback-path"
    }'

Webhook Callback

When a transaction occurs, the provided callback URL will be used to send updates. Whether the transaction is successful or unsuccessful, the webhook endpoint will be triggered using the POST method. You can find further details in the sample payload provided below.

If the transaction is unsuccessful, the statusCode field will be set to PAYMENT_REJECTED in the case of a payment rejection or GENERIC_ERROR if an error occurs during request processing.

{
  "statusCode: "PAYMENT_ACCEPTED",
  "transactionRef: "20f807fe-3ee8-4525-8aff-ccb95de38250",
  "transactionId": "X50jcLD-U"
}