Post a payment

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.

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. 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.

{
	"countryCode": "UG",
	"payload": {
		"credentials": {
			"username": "sandboxUser",
			"password": "sandboxPassword!"
		},
		"packet": [{
			"serviceCode": "UG-MTN-B2C",
			"MSISDN": "256787777777",
			"invoiceNumber": "",
			"accountNumber": "256787777777",
			"payerTransactionID": "yourUniqueID",
			"amount": 1000,
			"hubID": "",
			"narration": "MTN Mobile money",
			"datePaymentReceived": "2022-11-11 20:00:00",
			"extraData": {
				"callbackUrl": "https://yourCallBackUrl.com/receivePaymentStatus"
			},
			"currencyCode": "UGX",
			"customerNames": "John Doe",
			"paymentMode": "Online Payment"
		}]
	}
}
{
	"countryCode": "UG",
	"payload": {
		"credentials": {
			"username": "sandboxUser",
			"password": "sandboxPassword!"
		},
		"packet": [{
			"serviceCode": "UG-MTN-B2C",
			"MSISDN": "256777777777",
			"invoiceNumber": "",
			"accountNumber": "256777777777",
			"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"
		}]
	}
}
{
	"countryCode": "NG",
	"payload": {
		"credentials": {
			"username": "sandboxUser",
			"password": "sandboxPassword!"
		},
		"packet": [{
			"serviceCode": "NG-BANK-PAYOUT",
			"MSISDN": "256700000000",
			"accountNumber": "00072186",
			"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"
		}]
	}
}
{
	"countryCode": "KE",
	"payload": {
		"credentials": {
			"username": "sandboxUser",
			"password": "sandboxPassword!"
		},
		"packet": [{
			"serviceCode": "KE-SAFARICOM-AIRTIME",
			"MSISDN": "254777777777",
			"invoiceNumber": "",
			"accountNumber": "254777777777",
			"payerTransactionID": "yourUniqueID",
			"amount": 1000,
			"hubID": "",
			"narration": "Safaricom Airtime",
			"datePaymentReceived": "",
			"extraData": {
				"callbackUrl": "https://yourCallBackUrl.com/receivePaymentStatus"
			},
			"currencyCode": "KES",
			"customerNames": "John Doe",
			"paymentMode": "Online Payment"
		}]
	}
}
{
	"countryCode": "KE",
	"payload": {
		"credentials": {
			"username": "sandboxUser",
			"password": "sandboxPassword!"
		},
		"packet": [{
			"serviceCode": "KE-PREPAID-ELEC",
			"MSISDN": "254777777777",
			"invoiceNumber": "",
			"accountNumber": "042381176772",
			"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
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 ISO code for the transaction currency.yes
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

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

📘

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

Language
Click Try It! to start a request and see the response here!