Home
API Reference
Login

Post a payment

post
https://api-approval.tingg.africa/v1/global-api/payments

This API function is invoked by Merchants/Originating Clients, e.g., banks, mobile money providers, aggregators, etc., to post requests for airtime, mobile money, and payments to the Beep Server.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Use Cases

  1. Send Money (Payout) - B2C

Suitable for Mobile Money Payout Transactions B2C, Refunds, and Bulk Disbursement.

The source of funds will be a B2C Float account configured on our Payment Gateway. Therefore, the MSISDN and accountNumber can be similar.

  1. Bank Payouts

Suitable for bank transfers. Unlike other payloads, bank transfers have a few extra parameters nested in the extraData as an escape string.

destinationBankCode- This is simply the target bank identified by its unique code to which funds will be disbursed. E.g., 000201.
destinationBankName- A unique name for the subject bank. E.g., GTBank plc.

destinationAccountName- This Should be the account holder's name to where money is being sent, known as the target account. E.g., John Doe

destinationAccountNo- This should be the unique account number for the target account receiving the disbursed funds.

  1. RTGS Payment Integration Guide

Real-Time Gross Settlement (RTGS) is a high-value, immediate interbank settlement mechanism used for large domestic transfers in Kenya. Unlike batch-settled channels such as EFT or Pesalink, each RTGS transaction is settled individually and in real time through the Central Bank of Kenya (CBK) RTGS system.

RTGS is the recommended channel for transfers where:

  • The amount is large (typically KES 1,000,000 and above)
  • Immediate settlement is required
  • The beneficiary holds an account at a different domestic bank

Supporting Document Requirement

RTGS transactions are subject to the following rule based on the transfer amount:

AmountSupporting Document Required?
Less than KES 1,000,000No — proceed directly to payment
KES 1,000,000 and aboveYes — must be uploaded before initiating payment

Important

For transactions KES 1,000,000 and above, the payment will be rejected outright if a supportDocument reference is not present in the payment payload. Always upload the document first and obtain a reference before posting the payment.

Step-by-Step Flow for High-Value Transfers (>= KES 1,000,000)

Step 1 — Upload a Supporting Document

Before initiating a high-value RTGS payment, upload the supporting document to the Transaction File Service. The upload must include a payerTransactionId that will be used to link the document to the subsequent payment.

Request (multipart/form-data)

FieldTypeRequiredDescription
payerTransactionIdstringYesUnique reference you generate; must match the payerTransactionId sent in the payment event
filefileYesSupporting document — PDF format only

Example cURL

curl --location 'https://transaction-file-service.dev.tingg.africa/api/v1/transaction-documents' \
  --form 'payerTransactionId="PAYER-TXN-000123"' \
  --form 'file=@"/path/to/supporting-document.pdf"'

Accepted Supporting Documents

Note

The exact list of accepted document types is TBC and will be confirmed by the Tingg compliance team. Expected categories include (but may not be limited to):

  • Bank statements
  • Invoice / proforma invoice
  • Board resolution (for corporate payments)
  • Contract or agreement
  • Any other document required by CBK RTGS guidelines

Ensure the document is a valid, readable PDF before uploading. The file service may reject corrupted or password-protected files.

Step 2 — Submit the RTGS Payment

Important

The payerTransactionID used during document upload must match the value passed in payerTransactionID on the post-payment event. This is how the payment processor associates the uploaded document with the transaction.

Acknowledgement Responses

Status CodeMeaningDescription
148paymentDeliveredRTGS transfer successfully submitted to Choice Bank. receiptNumber contains the applicationId.
141rejectedPayment rejected — e.g. missing supportDocument for amounts >= 1,000,000.
140acceptedTransaction with reference [BankTrnxID] is successful

Note

RTGS is not synchronously settled. A paymentDelivered (148) response means the transfer has been accepted and queued for real-time interbank settlement, not that funds have already moved. Final settlement confirmation is delivered via callback.

  1. Airtime

Suitable for vending airtime/data.

For a self top up, the MSISDN and accountNumber params are similar. The phone number on the accountNumber param is the recipient of the top-up.

  1. Bill Payments

Suitable for bill payments, i.e., Dstv, Gotv, Prepaid Electricity, and much more.

The ability to fetch the bill amount and Due date for postpaid services, i.e., DSTV, GOTV, Postpaid Electricity, and water services before payment is provided by Beep.queryBill.

For Prepaid Electricity the token details and units will be provided on the final transaction response. i.e under the **receiverNarration **param.

{
	"function": "BEEP.postPayment",
	"countryCode": "UG",
	"payload": {
		"credentials": {
			"username": "sandboxUser",
			"password": "sandboxPassword!"
		},
		"packet": [{
			"serviceCode": "UG-MTN-B2C",
			"MSISDN": "256787777777",
			"invoiceNumber": "",
			"accountNumber": "256787777777",
      "countryCode": "UG",
			"payerTransactionID": "yourUniqueID",
			"amount": 1000,
			"hubID": "",
			"narration": "MTN Mobile money",
			"datePaymentReceived": "2022-11-11 20:00:00",
      "extraData": {
				"pushToOriginator": true,
				"callbackUrl": "https://yourCallBackUrl.com/receivePaymentStatus"
			},
			"currencyCode": "UGX",
			"customerNames": "John Doe",
			"paymentMode": "Online Payment"
		}]
	}
}
{
  "function": "BEEP.postPayment",
	"countryCode": "UG",
	"payload": {
		"credentials": {
			"username": "sandboxUser",
			"password": "sandboxPassword!"
		},
		"packet": [{
			"serviceCode": "UG-MTN-B2C",
			"MSISDN": "256777777777",
			"invoiceNumber": "",
			"accountNumber": "256777777777",
      "countryCode": "UG",
			"payerTransactionID": "yourUniqueID",
			"amount": 1000,
			"hubID": "",
			"narration": "MTN Mobile money",
			"datePaymentReceived": "2019-11-11 20:00:00",
			"extraData": {
				"callbackUrl": "https://yourCallBackUrl.com/receivePaymentStatus"
			},
			"currencyCode": "UGX",
			"customerNames": "Walter White",
			"paymentMode": "Online Payment"
		}]
	}
}
{
  "function": "BEEP.postPayment",
	"countryCode": "NG",
	"payload": {
		"credentials": {
			"username": "sandboxUser",
			"password": "sandboxPassword!"
		},
		"packet": [{
			"serviceCode": "NG-BANK-PAYOUT",
			"MSISDN": "256700000000",
			"accountNumber": "00072186",
      "countryCode": "NG",
			"payerTransactionID": "yourUniqueID",
			"amount": 50000,
			"narration": "Bank Payout",
			"datePaymentReceived": "2022-03-15 00:26:29",
			"extraData": {
				"callbackUrl": "https://yourCallBackUrl.com/receivePaymentStatus",
				"destinationBankCode": "000012",
				"destinationAccountName": "John Doe",
				"destinationAccountNo": "00072186",
				"destinationBank": "StanbicIBTC Bank"
			},
			"paymentMode": "BANK",
			"currencyCode": "NGN",
			"customerNames": "John Doe"
		}]
	}
}
{
  "function": "BEEP.postPayment",
	"countryCode": "KE",
	"payload": {
		"credentials": {
			"username": "sandboxUser",
			"password": "sandboxPassword!"
		},
		"packet": [{
			"serviceCode": "KE-SAFARICOM-AIRTIME",
			"MSISDN": "254777777777",
			"invoiceNumber": "",
			"accountNumber": "254777777777",
      "countryCode": "KE",
			"payerTransactionID": "yourUniqueID",
			"amount": 1000,
			"hubID": "",
			"narration": "Safaricom Airtime",
			"datePaymentReceived": "",
			"extraData": {
				"callbackUrl": "https://yourCallBackUrl.com/receivePaymentStatus"
			},
			"currencyCode": "KES",
			"customerNames": "John Doe",
			"paymentMode": "Online Payment"
		}]
	}
}
{
  "function": "BEEP.postPayment",
	"countryCode": "KE",
	"payload": {
		"credentials": {
			"username": "sandboxUser",
			"password": "sandboxPassword!"
		},
		"packet": [{
			"serviceCode": "KE-PREPAID-ELEC",
			"MSISDN": "254777777777",
			"invoiceNumber": "",
			"accountNumber": "042381176772",
      "countryCode": "KE",
			"payerTransactionID": "unique_trnsaction_id",
			"amount": 1000,
			"hubID": "",
			"narration": "Umeme Prepaid electricity",
			"datePaymentReceived": "2019-11-11 20:00:00",
			"extraData": {
				"callbackUrl": "https://yourCallBackUrl.com/receivePaymentStatus"
			},
			"currencyCode": "KES",
			"customerNames": "John Doe",
			"paymentMode": "Online Payment"
		}]
	}
}
ParameterTypeDescriptionRequired
functionstringFunction being invokedyes
countryCodestringCountry ISO code letter, i.e., KE,GH,TZyes
payloadobject
payload.credentialsobject
payload.credentials.usernamestringThe user name you created on sign-inyes
payload.credentials.passwordstringThe Password you created on sign-inyes
payload.packetarray
payload.packet.serviceCodestringProduct code identifying the service a customer is consuming, e.g., TIGOAIRTIME.List of ServiceCodesyes
payload.packet.MSISDNstringThe mobile number of the customer making the payment. The MSISDN should begin with a country code, e.g., 2547xxxxxxxxyes
payload.packet.invoiceNumberstringThe receiver (merchant) client system generates the reference ID for the transaction.no
payload.packet.accountNumberstringThe account number is the recipient of the payment. If it’s a mobile number, it should begin with a country code, e.g.,**254xxxxxxxxx**yes
payload.packet.payerTransactionIDstringThe unique transactionID generated by the bank for this transaction.yes
payload.packet.amountdoubleThe amount paid by the customer.yes
payload.packet.narrationstringA narration of the payment being made.no
payload.packet.datePaymentReceivedstringThe date the payer received payment. **yyyy-mm-dd hh:mm:ss**.yes
payload.packet.currencyCodestringThe two letter ISO code for the transaction currency.yes
payload.packet.countryCodestringThe two letter ISO code for the transaction countryyes
payload.packet.hubIDstringUnique hub transaction IDno
payload.packet.paymentModestringThe payment mode used for example ATM, Mobile, etcno
payload.packet.customerNamesstringThe name of the customer as given on the payer’s endno
payload.packet.extraDataobjectAny extra parameter or information you need to pass in a key-value JSON format, i.e., callBackUrlno
payload.packet.extraData.pushToOriginatorbooleanSet the value as "true" in order to enable callbacksno
payload.packet.extraData.callbackUrlstringProvide your callback URLno

Response

{
    "authStatus": {
        "authStatusCode": 131,
        "authStatusDescription": "Authentication was successful"
    },
    "results": [
        {
            "statusCode": 139,
            "statusDescription": "Payment pending acknowledgement",
            "payerTransactionID": "yourUniqueID",
            "beepTransactionID": 10324841472
        }
    ]
}

Auth Status

ParameterTypeDescription
authStatusCodeintAuthentication status code.
authStatusDescriptionstringA narration/ description for the status code above.

Authentication status codes returned from the BEEP.postPayment

statusCodestatusDescription
131Client authenticated successfully
132Client authentication failed
174Generic failure status code matching the appropriate description

PostPayment Status Codes

statusCodestatusDescription
104Generic exception occurred with matching appropriate description
106Inactive service
109Customer MSISDN missing
110Invalid Customer MSISDN
111Invalid invoice amount
115Invalid currency code specified
120Account number not specified
139Payment posted successfully and pending acknowledgement.
146Invoice does not exist
167Invalid serviceID
174Generic failure occurred with appropriate status description
229Duplicate payment found
230Insufficient Float Balance
231Amount specified is greater than maximum allowed for service
232Amount specified is less than minimum allowed for service
📘

Note: In the event of a 5xx server error response, do not immediately retry or return the transaction as failed. Instead, query the transaction status first using the appropriate status check API. This ensures you avoid duplicate processing and handle idempotency correctly.

Callback

📘

This API is asynchronous . You will receive final status of the transaction on your HTTP listener. Only statusCode 139 sends a callback .Refer to Callback from more information

Body Params
string
required
Defaults to KE
Responses

Updated about 3 hours ago

What’s Next

Did this page help you?
Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated about 3 hours ago

What’s Next

Did this page help you?