Direct Charge
You can conveniently collect payments through cards, banks, or any of our supported ways with just one integration using Lipad Checkout. It however comes with the Lipad checkout experience.
There are occasions when you want additional control that works with your app. Direct charge enters the picture here. We supply the APIs for clients to be charged, but you are responsible for gathering their payment information and bringing your own UI and payment flow. You can control and modify the customer experience however you like.
There are three main stages in direct charge:
- Initiate the payment: Send the charge request to the appropriate charge endpoints.
- Authorize the charge: Customer interacts with the payment prompts and completes the paymnent.
- Post callback payment verification: As a failsafe, you'll call our Status API to verify that the payment was successful before giving value.
Lipad Direct charge Transaction Flow
Direct Charge Transaction Flow Description
- The charge request originator (Client) captures and sets the API required parameters and sends the request to the respective charge endpoint.
- The API receives the request, validates it and sends an acknowledgement response back to the originator (Client).
- A charge request is initiated via the Payments Partner responsible eg Airtel Money or M-Pesa
- The Customer authorizes the transaction.
- The Payments Partner debits the customer and Credits LIPAD Wallet, sends payment result to LIPAD
- LIPAD processes the result, credits the Originator's LIPAD Wallet with funds from the payment.
- LIPAD Charge Service then sends Payment Notification webhook to the webhook URL registered on our system. (Type: Payments Notifications)
Authentication
All requests made to LIPAD Direct Charge APIs will require token authentication.
Authentication requests are send to:
POST https://dev.lipad.io/v1/auth
Authentication Request body
{
"consumer_key": "Xjpe948ixgdhlUrRNlOwc",
"consumer_secret": "hNjZK2JVm4Uc1whgskjsiY9G"
}
Response Body
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiIxNiIsImRlc2lnbmF0aW9uIjoiQXBpIFVzZXIiLCJhdXRob3JpemVkIjp0cnVlLCJpYXQiOjE2Nzc3MDY4ODgsImV4cCI6MTY3NzcxMjg4OH0.kADugWTjIrXokYYhDTXg4idmsLy6pUTv6N0Hi-ZMkrI",
"expiresIn": 6000
}
Use the token returned under access_token for all requests made to the Payouts APIs. The token should be passed as a Request Header x-access-token. The token will be valid for up to 1 hour.
Supported Payment Methods
Broadly we support the following payment method types in our Direct Charge Api:
- Mobile Money
Mobile Money
We support several MNOs(mobile network providers) across the continent. You can find several supported MNOs in the next section
The following table provides information about the Mobile Network Operators currently supported by our Direct Mobile Money Charge API.
Kenya
| Mobile Network Operator(MNO) | Lipad Short Code | Country | Currency |
|---|---|---|---|
| Safaricom MPESA | MPESA_KEN | KEN | KES |
| Airtel Kenya | AIRTEL_KEN | KEN | KES |
MPESA
This payment method allows you to receive KES payments via Mpesa.
POST https://dev.charge.lipad.io/v1/mobile-money/charge
The following is a payload structure expected by the mobile money charge endpoint;
{
"external_reference": "123456",
"origin_channel_code": "API",
"originator_msisdn": "2547****56",
"payer_msisdn": "254******56",
"service_code": "<client service code>",
"account_number": "123456789",
"invoice_number": "",
"currency_code": "KES",
"amount": "100",
"add_transaction_charge": false,
"transaction_charge": "0",
"payment_method_code": "<payment method code>",
"paybill": "123456",
"extra_data": {
},
"description": "Payment by 254700123456",
"notify_client": false,
"notify_originator": false
}
Request Body Parameters description
| Parameter | Data Type | Null | Description |
|---|---|---|---|
| external_reference | string | NO | This is the unique reference generated by the external/internal party requesting charge. It will be used to send a callback once charge is successful. |
| origin_channel_code | string | YES | This is an optional parameter indicating where the request to charge originated from. It has to be a valid channel code (API, WEB, USSD, APP) |
| originator_msisdn | string | NO | This is the mobile number of the individual initiating the request for charge. |
| payer_msisdn | string | NO | This is the mobile number that will be debited. It will receive the USSD or STK push. |
| service_code | string | NO | This is the service against which charge is being made. Once successful, a payment will be logged against this service. |
| account_number | string | NO | This is the account number against which the payment is being made. |
| invoice_number | string | YES | This is an internal invoice number to be used by the originating system. |
| currency_code | string | YES | This is the currency to be used to charge the client. |
| amount | string | NO | This is the service amount to be charged from the client. |
| add_transaction_charge | boolean | NO | Indicates whether the customer should be charged extra fees. |
| transaction_charge | string | NO | The transaction charge amount to be applied if the addTransactionCharge parameter is set to true. |
| payment_method_code | string | NO | The code to be used to identify the payment method. See LIPAD Short Codes on Supported MNOs section |
| paybill | string | NO | Parameter to indicate the paybill or till number or business name/code to be used when invoking the respective telcos. Use LIPAD_DEFAULT if none is configured |
| extra_data | json | YES | JSON array of any additional information to be captured during charge. The same information will be relayed back when sending payment callbacks. |
| description | string | YES | Description of the payment. |
| notify_client | boolean | NO | Tells charge whether to send an IPN to the owner client of the service using the callback URL configured under the client. |
| notify_originator | boolean | NO | Tells charge whether to send an IPN to the client who originated the charge request (Identified by credentials used to invoke charge). The IPN is sent using the callback URL configured under the client. |
Request Response Body
Once the mobile money charge is requested, an acknowledgement is sent back to the initiating channel or customer. The response could be successful or failed.
*Note: Be sure to checkout the status codes section to see the various statusCodes that can be returned.*
The payload structure shown below demonstrates a successful charge response;
{
"status_code": 102,
"status_description": "Request to charge customer was successfully placed",
"total_amount": "1900",
"service_amount": "1800",
"transaction_charge": "100",
"charge_request_id": 123456789,
"external_reference": “123456”
}
The following table describes the response payload above.
| Parameter | Data Type | Null | Description |
|---|---|---|---|
| status_code | int | NO | Status of the charge request. |
| status_description | string | NO | Description of the charge status. |
| total_amount | string | NO | Total amount charged from the customer. |
| service_amount | string | NO | Service amount from the total amount paid. |
| transaction_charge | string | NO | Charge amount from the total amount paid. |
| charge_request_id | int | NO | Internal Charge request ID. |
| external_reference | string | NO | This is the unique reference generated by the external/internal party that requested the charge. |
Error Response Body
{
"status_code": 172,
"status_description": "Could not initiate Charge Request",
"message": "Missing or Invalid access token"
}
Error Response Parameters Description
| Parameter | Description |
|---|---|
| status_code | Status of the charge request. See Status Codes Section |
| status_description | Description of the charge status |
| message | Error specific description |
AIRTEL MONEY
This payment method allows you to receive payments via Airtel Money.
POST https://dev.charge.lipad.io/v1/mobile-money/charge
The following is a payload structure expected by the mobile money charge endpoint;
{
"external_reference": "123456",
"origin_channel_code": "API",
"originator_msisdn": "2547****56",
"payer_msisdn": "254******56",
"service_code": "<client service code>",
"account_number": "123456789",
"invoice_number": "",
"currency_code": "KES",
"amount": "100",
"add_transaction_charge": false,
"transaction_charge": "0",
"payment_method_code": "<payment method code>",
"extra_data": {
},
"description": "Payment by 254700123456",
"notify_client": false,
"notify_originator": false
}
Request Body Parameters description
| Parameter | Data Type | Null | Description |
|---|---|---|---|
| external_reference | string | NO | This is the unique reference generated by the external/internal party requesting charge. It will be used to send a callback once charge is successful. |
| origin_channel_code | string | YES | This is an optional parameter indicating where the request to charge originated from. It has to be a valid channel code (API, WEB, USSD, APP) |
| originator_msisdn | string | NO | This is the mobile number of the individual initiating the request for charge. |
| payer_msisdn | string | NO | This is the mobile number that will be debited. It will receive the USSD or STK push. |
| service_code | string | NO | This is the service against which charge is being made. Once successful, a payment will be logged against this service. |
| account_number | string | NO | This is the account number against which the payment is being made. |
| invoice_number | string | YES | This is an internal invoice number to be used by the originating system. |
| currency_code | string | YES | This is the currency to be used to charge the client. |
| amount | string | NO | This is the service amount to be charged from the client. |
| add_transaction_charge | boolean | NO | Indicates whether the customer should be charged extra fees. |
| transaction_charge | string | NO | The transaction charge amount to be applied if the addTransactionCharge parameter is set to true. |
| payment_method_code | string | NO | The code to be used to identify the payment method. See LIPAD Short Codes on Supported MNOs section |
| paybill | string | NO | Parameter to indicate the paybill or till number or business name/code to be used when invoking the respective telcos. Use LIPAD_DEFAULT if none is configured |
| description | string | YES | Description of the payment. |
| notify_client | boolean | NO | Tells charge whether to send an IPN to the owner client of the service using the callback URL configured under the client. |
| notify_originator | boolean | NO | Tells charge whether to send an IPN to the client who originated the charge request (Identified by credentials used to invoke charge). The IPN is sent using the callback URL configured under the client. |
Request Response Body
Once the mobile money charge is requested, an acknowledgement is sent back to the initiating channel or customer. The response could be successful or failed.
*Note: Be sure to checkout the status codes section to see the various statusCodes that can be returned.*
The payload structure shown below demonstrates a successful charge response;
{
"status_code": 102,
"status_description": "Request to charge customer was successfully placed",
"total_amount": "1900",
"service_amount": "1800",
"transaction_charge": "100",
"charge_request_id": 123456789,
"external_reference": “123456”
}
The following table describes the response payload above.
| Parameter | Data Type | Null | Description |
|---|---|---|---|
| status_code | int | NO | Status of the charge request. |
| status_description | string | NO | Description of the charge status. |
| total_amount | string | NO | Total amount charged from the customer. |
| service_amount | string | NO | Service amount from the total amount paid. |
| transaction_charge | string | NO | Charge amount from the total amount paid. |
| charge_request_id | int | NO | Internal Charge request ID. |
| external_reference | string | NO | This is the unique reference generated by the external/internal party that requested the charge. |
Error Response Body
{
"status_code": 172,
"status_description": "Could not initiate Charge Request",
"message": "Missing or Invalid access token"
}
Error Response Parameters Description
| Parameter | Description |
|---|---|
| status_code | Status of the charge request. See Status Codes Section |
| status_description | Description of the charge status |
| message | Error specific description |
Callbacks
Once payment is made against a charge request by the customer, a callback shall be sent back to the client of the service or originator of the payment request. This payment notification is sent back to the client depending on the notify_client or notify_originator parameters that were sent during charge initiation.
NOTE:
- All callbacks from LIPAD employ Basic authentication with the username and password registered alongside the callback url. See Basic Authentication rfc for guidance.
- Do not rely entirely on webhooks for Charge request status. Use the LIPAD Charge Status API to verify a Payout Status
- Acknowledge webhook receipt with the following response
Payment result acknowledgement Response Body
{
"charge_request_id": "123",
"acknowledgement_code": "900",
"acknowledgement_description": "payment accepted",
"payment_id": "12345"
}
Payment result acknowledgement Response Body Parameters description
| Parameter | Description |
|---|---|
| charge_request_id | The incoming charge request ID |
| acknowledgement_code | A status code that indicates whether a request was accepted or rejected.
|
| acknowledgement_description | Callback receipt acknowledgement status description |
| payment_id | The incoming IPN payment ID |
NOTE: Unacknowledged callbacks will be retried 3 times over the next 48 hours after which no further webhooks will be sent.
Payment Result Body
{
"event": "successful_payment",
"amount": "2.00",
"extra_data": "extraData",
"client_code": "ATL-6815O1F",
"country_code": "KEN",
"payer_msisdn": "2547XXXXXXXX",
"payment_date": "2023-02-21T10:15:47.862Z",
"service_code": "EATZ_CHECKOUT",
"currency_code": "KES",
"account_number": "2547XXXXXXXX",
"payment_status": 700,
"transaction_id": "2019",
"payer_narration": "2547XXXXXXXX",
"charge_request_id": "873",
"external_reference": "1431",
"receiver_narration": "The service request is processed successfully.",
"payment_method_code": "MPESA_KEN",
"payer_transaction_id": "RBL35TKMUH"
}
Result Parameters description
| Name | Type | Description |
|---|---|---|
| event | String | Indicates payment event e.g failed_payment or successful_payment |
| amount | String | Amount paid by customer. |
| extra_data | String | Extra data passed during redirect |
| client_code | String | Merchant client code |
| country_code | String | The 3 digit ISO of the country which the payment was made from. |
| payer_msisdn | String | This is the mobile number that will be debited. It will receive the USSD or STK push. |
| payment_date | String | Date which payment was made. |
| service_code | String | The service for which the payment request was made. |
| currency_code | String | This is the currency to be used to charge the client. |
| account_number | String | This is the account number against which the payment is being made. |
| payment_status | String | Indicates payment status i.e
|
| transaction_id | String | Unique transaction id generated by Lipad. |
| payer_narration | String | Request description initally sent by Merchant. |
| charge_request_id | String | Unique charge id generated by Lipad. |
| external_reference | String | Unique charge id generated by Checkout. |
| receiver_narration | String | Narration generated by payment gateway. |
| payment_method_code | String | The payment method to be used to charge customer. |
| payer_transaction_id | String | Id generated by payment gateway. |
Charge Request Status
For status verification or in the event when result callbacks fail, the Charge Request Status API can be employed. Requests to check payout status are sent to:
GET <https://dev.charge.lipad.io/v1/transaction/{charge_request_id}/status
NOTE: For charge status Response Body and Parameters description, see Callbacks section.
Charge Request-Result Payment Status Codes
This flag indicates the individual payment status i.e successful or failed.
| Status | Description |
|---|---|
| 700 | Successful payment made. |
| 701 | Failed payment made |
| 702 | Payment was Reversed |
| 703 | Payment is Pending Processing |
| 704 | Payment is Jammed. Requires manual intervention to continue processing |
Charge Request-Response Status Codes
The status codes below will be used to indicate the status of the charge request made.
| Status Code | Status Message | Comment |
|---|---|---|
| 176 | CHARGE POSTED SUCCESSFULLY | This is the success code for posting a charge request. |
| 173 | GENERIC SUCCESS | GENERIC SUCCESS |
| 174 | GENERIC FAILURE | GENERIC FAILURE |
| 172 | GENERIC VALIDATION FAILURE | This is the generic code to be returned for generic validations. |
| 132 | Invalid Credentials. Authentication failed | Invalid Credentials. Authentication failed |
| 131 | Authentication was a success | Authentication was a success |
| 120 | INVOICE ACCOUNT NUMBER NOT SPECIFIED | This is the error code for when the invoice account number is not specified. |
| 110 | INVALID CUSTOMER MSISDN | This is the error code for a failed msisdn |
| 109 | CUSTOMER MSISDN MISSING | Missing Payer MSISDN |
| 115 | INVALID CURRENCY CODE | Currency error |