After completing the flow on the client side, your server needs to manage a few more things to complete your integration. Your client should forward the response received from the Standard Checkout to your server so you can decide what to do with the transaction. These steps are extremely important to protect your business and a lot of care should be taken in developing the logic to mark an Order as paid on your side.
Understanding the Response
The response received from your client includes the following information. Please familiarise your self with the fields so that it's easy for you to understand the next steps that need to be taken to process the response on your server.
{
"status": "success", // this is the Response Status - possible values are `success`, `failed` or `pending`
"message": "",
"nimbbl_order_id": "o_5aezw98nG8KLozP1", // this is the Nimbbl Order ID
"nimbbl_transaction_id": "o_5aezw98nG8KLozP1-230808065657", // this is the Nimbbl Transaction ID
"nimbbl_signature": "7e754ab8859f3ff888545ce73a0848bf131a468e543de5d9872128bc05d085ab", // this is the Signature generated for this transaction
"transaction": { // transaction object contains further information on the Transaction
"transaction_id": "o_5aezw98nG8KLozP1-230808065657", // this is the Nimbbl Transaction ID, same as above
"status": "succeeded", // this is the Transaction Status possible values are `succeeded`, `failed`, `pending`, `reversed` or `reversing`
"transaction_amount": 12.50, // this is the final transaction amount paid by the customer
"transaction_type": "payment", // this is the type of the transaction with possible values `payment`, `partial-refund`and `full-refund`
"transaction_currency": "INR", // this is the currency of the transaction
"additional_charges": 0.00, // this is the convenience fee applied on the transaction
"offer_discount": 0.00, // this is the offer discount applied on the transaction
"offer_id": "offer_fhdjsfmfdbfmsd", // If the offer is applied this will be the id of the offer
"payment_partner": "", // this is the Payment Partner that processed the payment
"psp_transaction_id": "", // this is the Transaction ID of the Payment Partner
"nimbbl_consumer_message": "", // this is the message that can be shown to the customer when transaction has `failed`
"nimbbl_merchant_message": "",
"nimbbl_error_code": "",
"signature": "7e754ab8859f3ff888545ce73a0848bf131a468e543de5d9872128bc05d085ab",
"signature_version": "v3" // this the version of the signature returned
},
"order": { // order object contains further information on the Order
"invoice_id": "9RZvgJOpAyJOd7Yx", // this is the Invoice ID, your unique reference for generating the Order
"status": "completed", // this is the order status, possible values are `new`, `pending`, `completed` or `lapsed`
"refund_details": { // this field will only come when the order_status is `completed`. This object will have all the refund details for the order.
"refundable_currency": "INR", // this is the currency in which the refund will be initiated
"available_refundable_amount": 5.0, // this is the amount which is available for refund
"refunded_amount": 0.0, // this is the amount which has been already refunded successfully
"total_refundable_amount": 5.0 // this is the maximum refundable amount available for the order
},
"currency_conversion": { // this object is sent only if the transaction currency was changed.
"original_currency": "USD", // this is the currency in which the order was initiated
"converted_currency": "INR", // this is the currency in which the order will be processed in
"exchange_rate": 100.0, // this is the exchange rate used to convert amounts from original currency to converted currency
"conversion_reason": "ALTERNATE_CURRENCY_CONFIG", // this is the reason for currency conversion
"original_amount_before_tax": 8.0, // this is the `amount_before_tax` received when the order was initiated
"original_tax": 2.0, // this is the `tax` when the order was initiated
"original_total_amount": 10.0 // this is the `total_amount` received when the order was initiate
}
}
}
Processing the Response
Depending on the response received, you can determine your next action as detailed in the table below. Where the recommended action is to Validate the response signature, please click on the link and follow the steps in validating the signature. This is an extremely important step to protect yourself from tampering fraud.
| Response Status | Transaction Status | Order Status | What does it Mean? | Next Action | How to try another Payment? |
|---|---|---|---|---|---|
success | succeeded | completed | Order has been successfully paid by the customer | Validate the response signature to check if the signature is matching. If the signature is matching, provide goods or services to your customer | Another payment isn't required as the Order is completed |
failed | null | new | User has cancelled the checkout without attempting any payment. There are more attempts remaining | Nothing needs to be done in this case. Since the transaction wasn't initiated, no need to provide any goods or services | If your user wants to pay again, you can launch the checkout again without creating a new order_id |
failed | failed | pending | User has attempted to pay and the last payment attempt has failed. There are more attempts remaining | Validate the response signature to check if the signature is matching. Since the transaction has failed, no need to provide any goods or services | If your user wants to pay again, can launch the checkout again without creating a new order_id |
pending | pending | pending | User has attempted to pay for the order but no status is available for the last attempt. There are more attempts remaining | Validate the response signature to check if the signature is matching. Since the transaction is pending, no need to provide any goods or services. You can also periodically enquire the status of the transaction or consume webhooks to be updated | If your user wants to pay again, can launch the checkout again without creating a new order_id |
failed | failed | lapsed | User has attempted to pay and the last payment attempt has failed. There are no more attempts remaining | Validate the response signature to check if the signature is matching. Since the transaction has failed, no need to provide any goods or services | Another payment isn't possible on this Order as it is lapsed i.e. no more attempts remaining to pay. A new Order can be created |
pending | pending | lapsed | User has attempted to pay for the order but no status is available for the last attempt. There are no more attempts remaining | Validate the response signature to check if the signature is matching. Since the transaction is pending, no need to provide any goods or services. You can also periodically enquire the status of the transaction or consume webhooks to be updated | Another payment isn't possible on this Order as it is lapsed i.e. no more attempts remaining to pay. A new Order can be created |
Understanding & Handling Edge Cases
Despite the best effort of all parties involved in processing payments, transactions do not always succeed in real time and there may be rare scenarios where we have returned the Transaction Status as pending. Similarly, there may be instances, where your server is unable to get the response from your client.
Before getting into how to keep your system updated to handle these edge cases, it will be good to understand in detail the Transaction States and how they move from one state to another.
| Transaction Status | Meaning | Possible Future States |
|---|---|---|
pending | transaction is still under process and Nimbbl doesn't have the final status | failed, succeeded, reversing, reversed |
failed | transaction has failed, no goods or services should be provided to your customer | succeeded, reversing, reversed |
succeeded | transaction is a success and goods or services can be provided to your customer | this is always a final status |
reversing | transaction was successful after the authorisation period and an automatic refund request has been placed | reversed |
reversed | transaction was successful after the authorisation period and has been automatically refunded | this is always a final status |
- Sometimes transactions don't succeed in real time but after a delay of few minutes to hours or days
- As a business, you can configure the authorisation period for yourself between 5 minutes and 5 days, please reach out to help@nimbbl.biz with your preferred authorisation period
- If a transaction becomes successful after the authorisation period, the transaction will be automatically refunded
In all of these edge case scenarios where you are unable to get the response from your client or have received a pending status or the status has changed at a future time, there are APIs and webhooks that can be configured so you can always keep your system up to date
Performing Refunds
The final piece of integration work that you need to complete is to decide how you want to process refunds when your customer returns the goods or cancels their order. The linked document provides all the options that you have and how to proceed with the integration.
Refund transactions can have the following states.
| Transaction Status | Meaning | Possible Future States |
|---|---|---|
pending | refund transaction is still under process and Nimbbl doesn't have the final status | failed, succeeded |
failed | refund transaction has failed | this is always a final status |
succeeded | refund transaction is a success | this is always a final status |
APIs and webhooks can be configured for refund transactions as well, so you can always keep your system up to date