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
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
MSISDNandaccountNumbercan be similar.
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.
Suitable for vending airtime/data.
For a self top up, the
MSISDNandaccountNumberparams are similar. The phone number on the accountNumber param is the recipient of the top-up.
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"
}]
}
}
| Parameter | Type | Description | Required |
|---|---|---|---|
| countryCode | string | Country ISO code letter, i.e., KE,GH,TZ | yes |
| payload | object | ||
| payload.credentials | object | ||
| payload.credentials.username | string | The user name you created on sign-in | yes |
| payload.credentials.password | string | The Password you created on sign-in | yes |
| payload.packet | array | ||
| payload.packet.serviceCode | string | Product code identifying the service a customer is consuming, e.g., TIGOAIRTIME.List of ServiceCodes | yes |
| payload.packet.MSISDN | string | The mobile number of the customer making the payment. The MSISDN should begin with a country code, e.g., 2547xxxxxxxx | yes |
| payload.packet.invoiceNumber | string | The receiver (merchant) client system generates the reference ID for the transaction. | no |
| payload.packet.accountNumber | string | The 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.payerTransactionID | string | The unique transactionID generated by the bank for this transaction. | yes |
| payload.packet.amount | double | The amount paid by the customer. | yes |
| payload.packet.narration | string | A narration of the payment being made. | no |
| payload.packet.datePaymentReceived | string | The date the payer received payment. **yyyy-mm-dd hh:mm:ss**. | yes |
| payload.packet.currencyCode | string | The ISO code for the transaction currency. | yes |
| payload.packet.hubID | string | Unique hub transaction ID | no |
| payload.packet.paymentMode | string | The payment mode used for example ATM, Mobile, etc | no |
| payload.packet.customerNames | string | The name of the customer as given on the payer’s end | no |
| payload.packet.extraData | object | Any extra parameter or information you need to pass in a key-value JSON format, i.e., callBackUrl | no |
Response
{
"authStatus": {
"authStatusCode": 131,
"authStatusDescription": "Authentication was successful"
},
"results": [
{
"statusCode": 139,
"statusDescription": "Payment pending acknowledgement",
"payerTransactionID": "yourUniqueID",
"beepTransactionID": 10324841472
}
]
}
Auth Status
| Parameter | Type | Description |
|---|---|---|
| authStatusCode | int | Authentication status code. |
| authStatusDescription | string | A narration/ description for the status code above. |
Authentication status codes returned from the BEEP.postPayment
| statusCode | statusDescription |
|---|---|
| 131 | Client authenticated successfully |
| 132 | Client authentication failed |
| 174 | Generic failure status code matching the appropriate description |
PostPayment Status Codes
| statusCode | statusDescription |
|---|---|
| 104 | Generic exception occurred with matching appropriate description |
| 106 | Inactive service |
| 109 | Customer MSISDN missing |
| 110 | Invalid Customer MSISDN |
| 111 | Invalid invoice amount |
| 115 | Invalid currency code specified |
| 120 | Account number not specified |
| 139 | Payment posted successfully and pending acknowledgement. |
| 146 | Invoice does not exist |
| 167 | Invalid serviceID |
| 174 | Generic failure occurred with appropriate status description |
| 229 | Duplicate payment found |
| 230 | Insufficient Float Balance |
| 231 | Amount specified is greater than maximum allowed for service |
| 232 | Amount 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