Payment Status API FAQs
Payment status API FAQs
What is the payment status api?
The Payment Status API is a mandatory interface provided by partners (e.g., banks) integrating with Nuclei's SDK. It enables Nuclei to check the status of transactions initiated and processed through the partner's system.
Who will provide the payment status api?
The partner integrating with the Nuclei SDK must provide the Payment Status API as part of the integration process.
Why is the Payment Status API needed if a Callback API is already integrated?
The Payment Status API serves as a fallback mechanism. It allows Nuclei to retrieve transaction statuses for cases where the partner does not send a terminal state (e.g., SUCCESS/FAILURE) via the Callback API within the expected timeframe.
Which API takes precedence: Payment Status or Callback?
The Callback API is the primary mechanism for transaction updates. However, if a callback is not received within a specified period, the Nuclei server polls the Payment Status API a predetermined number of times. Whichever API first delivers a terminal state (SUCCESS/FAILURE) will determine the transaction's final status.
How many times will the Payment Status API be polled for a transaction?
The maximum polling attempts are configurable and determined collaboratively by the partner and the Nuclei team. By default, Nuclei polls the Payment Status API up to 5 times at fixed intervals, though this can be fine tuned as per requirement.
What is the interval between successive polling attempts?
Polling intervals are configurable. A typical example might follow a sequence like 3 min, 6 min, 9 min, 11 min. The interval configuration is agreed upon between the partner and the Nuclei team.
Will the Payment Status API be called if a terminal state is received via Callback?
No. If the transaction reaches a terminal state via the Callback API, Nuclei will not poll the Payment Status API for that transaction.
What should be the request / response format of the payment status api?
Detailed request and response formats can be found in the Payment Status API section under Payments Integration in the Getting Started section.
How is the signature for the X-Body-Signature header generated?
Refer to the Checksum Generation section under Payments Integration in the Getting Started guide for signature generation details.
What secret key should be used to generate the signature?
The shared partner secret key (not the SDK key) should be used to generate the checksum.
What should be done in case of signature mismatch errors?
Verify the secret key used for checksum generation. If the issue persists, contact the Nuclei team to revalidate the partner secret key.
Is the signature generation logic the same for Payment Status and Callback APIs?
Yes, the same signature generation logic applies to both APIs using the shared partner secret key.
Is the partner secret key different for UAT and Production environments?
Yes. Separate partner secret keys will be provided for UAT and Production environments during the integration process.
What status should be sent for transactions in an intermediate state?
For intermediate states, the status should be sent as IN-PROGRESS.
What happens if FAILURE is sent for an intermediate transaction, but SUCCESS is later sent via Callback?
If FAILURE is sent in the Payment Status API response before a SUCCESS callback is received, the transaction will be marked as FAILED at Nuclei's end. This will result in the order being considered failed, even if a successful payment occurred. Avoid sending FAILURE for intermediate states to prevent such conflicts.
Will there be multiple transaction status queries in one request?
No, Nuclei server would poll for a single transaction in one request.
What happens if the Payment Status API is unavailable during polling?
If the Payment Status API is unreachable or returns an error (e.g., 500 or timeout), the Nuclei server will retry based on the configured polling attempts and intervals.
What happens if the Payment Status API returns inconsistent states?
For example, if an intermediate state (IN-PROGRESS) is returned after a terminal state (SUCCESS/FAILURE):
- Nuclei will prioritize the first terminal state received.
- Any inconsistencies should be avoided during integration testing in UAT/ CUG.