3. Post Charge Request
Allows a merchant to request to debit amount from customer for the checkout request that was posted earlier in the request/initiate function.
POST https://developer.tingg.africa/checkout/v2/custom/requests/charge
The charge request can only be initiated on a record that has not expired and is not fully paid.
The data in this function will partly be provided and validated using the result received from the post checkout request function. The post charge request function does the following:
- Create a charge request in the checkout platform tied to a checkout request.
- Based on the payment mode available for the payment option, initiate a request for payment authorization e.g. STK prompt. See the different payment flows available on the Payment Experiences section.
This extra step is to help you verify the customer transacting by requiring them to validate a system generated O.T.P sent to the phone number used to initiate the charge.
For Ghana merchants this step is mandatory to help reduce the multiple reported fraudulent requests. If the OTP validation is not implemented in any way then the service will be switched off.
Header Parameters
| Header | Value | Required |
|---|---|---|
| Authorization | Bearer <Bearer_Token> generated during authenticate request in step 1. | YES |
| Content-Type | application/json | YES |
Request Parameters
| Parameter Name | Type | Description | Required |
|---|---|---|---|
| merchantTransactionID | string | The unique transaction ID from the merchant's system identifying the request that was previously initiated on the post checkout request leg. | TRUE |
| checkoutRequestID | integer | A unique transaction ID identifying the transaction logged in the checkout platform. | TRUE |
| chargeMSISDN | string | The mobile number which will be used to initiate a charge request with. For some payment options, this has to be the local number in the country that the options exist in. | TRUE |
| chargeAmount | double | An amount to request from the customer. This will be used to raise an STK/USSD push or charge using any inline models. Should not be more than the maximum amount for the payment option | TRUE |
| currencyCode | string | Currency code representing the currency of the charge amount | TRUE |
| payerModeID | integer | This is a number representing the payment option client and the mode in use e.g. using a mobile money client paying via STK push. This will be provided as part of the payment options. | TRUE |
| languageCode | string | This is a two digit code in which the available instructions will be provided. | TRUE |
Example
{
"merchantTransactionID" : "<merchant_transaction_id",
"checkoutRequestID" : "<checkout_request_id",
"chargeMsisdn" : "<valid_mobile_number>", // 254700000000
"chargeAmount" : 10,
"currencyCode":"desired_currency",
"payerModeID": "<id_retrieved_from_payment_options>",
"languageCode":"en"
}
Response Parameters
| Parameter Name | Type | Description |
|---|---|---|
| statusCode | integer | Request status code. See full status code details below. 200 - Checkout request status fetched successfully from the checkout platform 500 - Generic failure occurred. Could be as a result of a system failure on the checkout platform 1001 - No checkout request found. 1007 - Missing countryCode.1013 - The checkout request posted was not valid JSON 1014 - Missing merchantTransactionID.1015 - Missing checkoutRequestID.1017 - Invalid charge MSISDN provided.1027 - Invalid amount provided. The chargeAmount should be between the minimum and maximum amounts provided for the payment option. |
| statusDescription | string | Description of the transaction status. |
| checkoutRequestID | integer | The unique request identifying the transaction logged in the checkout platform. |
| merchantRequestID | string | The unique transaction ID from merchant's system identifying the request. |
| chargeRequestID | integer | A unique identifier for the charge request as stored on our database. |
| paymentInstructions | string | Instructions to provide to the customer on how to make a payment. |
| languageCode | string | A two letter code representing the language that the instructions are in. |
| chargeMSISDN | integer | The charge mobile number provided earlier in the request. |
| chargeAmount | integer | The charge amount as was provided earlier in the request. |
| chargeRequestDate | string | The date and time in which the charge request was logged. This will be in UTC time. |
| thirdPartyResponse | JSON Object | Applicable to Bank Transfer Nigeria and MPesa Kenya |
| paymentRedirectUrl | string | The payment provider link to complete the payment request |
Examples
Successful Response
{
"status": {
"statusCode": 200,
"statusDescription": "Successfully created a charge request"
},
"results": {
"checkoutRequestID": "407134",
"merchantTransactionID": "MTX2258549",
"chargeRequestID": 78380,
"paymentInstructions": "<p>You will receive a prompt on mobile number <b>254700000000</b>.<br/> Enter your M-Pesa PIN to authorize your payment of <b>KES 10</b> to account number <b>ACC12345</b>. </p>",
"languageCode": "en",
"chargeMsisdn": 254700000000,
"chargeAmount": 10,
"chargeRequestDate": "2020-08-27 08:11:20",
"redirectUrl": "<YOUR_REDIRECT_URL>"
}
}
Response with ThirdPartyResponse Parameter for Bank Transfer Nigeria
{
"status": {
"statusCode": 200,
"statusDescription": "Successfully created a charge request"
},
"results": {
"checkoutRequestID": 51713726,
"merchantTransactionID": "id_9639033",
"chargeRequestID": 40645434,
"paymentInstructions": "<p>Please make a payment of <b>NGN 10.00</b> to the following account.</p><p><table><tr><td>Account number:</td><td></td><td></td><td><b>8466027823</b></td></tr><tr></tr><tr></tr><tr></tr><tr><td>Bank Name:</td><td></td><td></td><td> Wema Bank</td></tr><tr></tr><tr></tr><tr></tr><tr></tr><tr><td>Beneficiary:</td><td></td><td></td><td> <b>Checkout Demo Service</b></td></tr><tr></tr></table></p><p><b>Reminder: Use this account only for this transaction, and make sure to complete the payment before the time specified above expires. </b></p>",
"languageCode": "en",
"chargeMsisdn": "254723149420",
"chargeAmount": 10,
"chargeRequestDate": "2023-03-29 15:20:34",
"thirdPartyResponse": {
"tinggVirtualAccountID": "8466027823",
"tinggAccount": "8466027823",
"tinggBank": "WEMA",
"tinggName": "1683008682_MULADEMO_test-demo"
},
"paymentRedirectUrl": ""
}
}
Response with ThirdPartyResponse Parameter for MPesa
{
"status": {
"statusCode": 200,
"statusDescription": "Successfully created a charge request"
},
"results": {
"checkoutRequestID": 51713726,
"merchantTransactionID": "id_9639033",
"chargeRequestID": 40645434,
"paymentInstructions": "<p>Please make a payment of <b>NGN 10.00</b> to the following account.</p><p><table><tr><td>Account number:</td><td></td><td></td><td><b>8466027823</b></td></tr><tr></tr><tr></tr><tr></tr><tr><td>Bank Name:</td><td></td><td></td><td> Wema Bank</td></tr><tr></tr><tr></tr><tr></tr><tr></tr><tr><td>Beneficiary:</td><td></td><td></td><td> <b>Checkout Demo Service</b></td></tr><tr></tr></table></p><p><b>Reminder: Use this account only for this transaction, and make sure to complete the payment before the time specified above expires. </b></p>",
"languageCode": "en",
"chargeMsisdn": "254723149420",
"chargeAmount": 10,
"chargeRequestDate": "2023-03-29 15:20:34",
"thirdPartyResponse": "{\"authStatus\":{\"authStatusCode\":131,\"authStatusDescription\":\"Authentication was successful.\"},\"results\":[{\"statusCode\":176,\"statusDescription\":\"Charge posted successfully.\",\"chargeRequestID\":16125740,\"chargeRequestUUID\":\"132CW9H\",\"paymentReferenceNumber\":\"132CW9H\",\"paymentCorrelationID\":16129042,\"chargeRequestCorrelationID\":1684290011,\"totalTransactionCharges\":0.0,\"totalChargeBeneficiaries\":0.0,\"totalAmount\":1.0}]}",
"paymentRedirectUrl": "https://paymentpage.dev"
}
}
Failure Response
{
"status": {
"statusCode": 1014,
"statusDescription": "The merchant transaction i d field is required."
},
"results": null
}
Authentication Failure Response
{
"message": "Unauthenticated.",
"status_code": 500
}
Updated 15 days ago