Frequently Asked Questions (FAQ)

1. What is the difference between Full Stack Integration and Fulfillment-Only Integration?

There are two integration models supported:

• Full Stack Integration: Recommended for partners who want to build the entire recharge journey. It includes APIs for operator detection, plan discovery, validation, fulfillment, and status tracking.

• Fulfillment-Only Integration: Ideal for partners who already handle operator logic and plan browsing. These partners can skip the discovery and validation APIs and only use fulfillment, callback, and status APIs.

2. Do I need to use all the APIs under the Full Stack model?

No. Even within the Full Stack integration, all APIs are not mandatory. You can selectively implement only the APIs that suit your use case. For example, if you already detect the operator yourself, you may skip the /fetch-operators API. The architecture is modular and flexible.

3. Why is hybrid encryption used, and how does it work?

Hybrid encryption ensures security and performance by combining:

• RSA encryption for encrypting the AES key (symmetric key).
• AES encryption for the actual payload.

Each request requires two fields:

• encryptedKey (AES key encrypted with RSA)
• encryptedData (actual payload encrypted using AES)

4. What happens if decryption fails at Nuclei’s end?

You will receive a 401 Unauthorized status code with error code 700, indicating decryption failure. Please verify your encryption logic, public/private key pairs, and request payload.

5. Do I need to share my IP addresses?

Yes. IP whitelisting is mandatory. Partners must share their UAT and Production server IPs with Nuclei to enable access to the APIs.

6. Is HTTPS mandatory for API access?

Yes. All API traffic must use the HTTPS protocol to ensure encrypted and secure communication.

7. Are both encryptedKey and encryptedData required in every request?
Yes. All requests to Nuclei’s APIs must contain these two fields in the request body. These ensure the payload is securely transmitted.

8. Where do I get the API Key from?
Nuclei will provide the API Key during onboarding. It must be included in the API-Key request header for every API call.

9. Can I initiate a recharge without validating the plan first?
It is not recommended. Always call the /operator-validation API before invoking the /fulfilment API. This reduces downstream failures due to plan-specific constraints.

10. What is the purpose of the referenceId in the Fulfillment API?

The referenceId is a unique transaction identifier provided by the partner. It is used to:

• Prevent duplicate recharge requests.
• Track recharge status via the /fulfilment-status API.

Nuclei uses this ID to deduplicate and trace transactions.

11. A plan is visible in /browse-plan but fails validation. Why?
Some plans have special conditions (e.g., applicable only for Jio Phone customers). While /browse-plan provides available plans, /operator-validation confirms if a selected plan is valid for a specific user.

12. What URL should I provide for callbacks?
Partners must provide a callback URL (separate for UAT and Production) that accepts POST requests. Nuclei will send the final status of the recharge to this URL once the transaction reaches a terminal state.

13. What if the callback is missed or fails to reach my server?
You can use the /fulfilment-status API to poll the current status using the original referenceId.

14. What are the possible status values from the /fulfilment-status API?

The recharge status can be one of the following:

    •    SUCCESS
    •    FAILURE
    •    IN PROGRESS
    •    NOT FOUND (referenceId does not exist)

15. How do I test the integration?

You will receive sandbox (UAT) API credentials from Nuclei. Use these to simulate complete recharge flows, including edge cases, before moving to production.

16. What is the process to go live?

Follow the steps outlined in the Go-Live Process:

        1.Sandbox access and integration
        2.UI/UX readiness
        3.End-to-end UAT testing
        4.Submit a request for production access (with IPs, callback URL, etc.)
        5.Perform dry run with real numbers
        6.Receive go-live approval
        7.Launch for end users with monitoring enabled

17. What does HTTP 429 mean?

This indicates too many requests in a short span. Implement rate limiting or retry with exponential backoff to avoid this error.

18. What does error code 803 indicate?

Error code 803 typically refers to constraint violations such as:

    •    Missing mandatory fields
    •    Invalid or out-of-bound values (e.g., mobile number, amount)
    •    Incorrect data types or payload structure

19. Where can I find the list of operator and circle codes?
Operator and circle codes are provided in the final section of this document. Use these IDs in your requests when specifying operatorCode and circleCode.

20. How frequently should the partner call the /browse-plan API?
Partners can call the /browse-plan API once a day and cache the response in their system. This local storage can then be used to display plans to users, ensuring a much faster and smoother experience. Since prepaid recharge plans do not change frequently, updating them once daily is sufficient to cater to user needs without any loss in accuracy or relevance.

Frequently Asked Questions (FAQ)​

Frequently Asked Questions (FAQ)