Skip to main content

API Reference — RESTful endpoints for payment integration

Version: 3.0.0

Introduction

RESTful APIs for integrating Nimbbl payments into your application. All responses are JSON.

Base URL​

All API requests use the base URL https://api.nimbbl.tech.

Authentication​

Every API call requires a Bearer token (JWT) in the Authorization header.

Authorization: Bearer <your_token>

Nimbbl uses two types of tokens, each designed for a specific context:

Merchant Token​

Generated by calling the Generate Token endpoint with your access_key and access_secret from Command Center > Developer Settings. This token is valid for 20 minutes. Use it for operations that involve sensitive data or administrative actions:

Security Warning

The merchant token grants full access to your account's API capabilities, including refunds and order management. Never embed it in your website's JavaScript, mobile app code, or any application that runs on the end user's device. It should only be used in your backend server code, where it is not visible to customers or third parties.

Order Token​

Returned in the Create Order and Get Order responses. Scoped to a single order and valid for 20 minutes.

Safe for client-side use

The order token is designed to be embedded in your website JavaScript, mobile app, or any customer-facing application. It only grants access to checkout operations for a single order and returns masked PII — so there is no risk in exposing it to end users.

With a Nimbbl SDK — pass the order token when initializing the checkout SDK (Web, Android, iOS, React Native, Flutter). The SDK handles the rest.

With direct API calls — if you are building a custom checkout, use the order token for all client-side calls:

If the token expires, call Get Order with your merchant token from your server to get a fresh one.

Data Security​

PII Masking​

To protect customer privacy in compliance with the DPDP Act, Nimbbl masks personally identifiable information (PII) in API responses based on which token you use:

  • Merchant token — returns unmasked PII (full name, email, phone number, address). Use server-to-server calls with this token when you need complete customer data for KYC, compliance, or reconciliation.
  • Order token — returns masked PII (e.g., D**** P*****, +91 ******3210). This protects customer data when API calls originate from the client side.

For a full list of masked fields and how to securely access unmasked data, see the Handling PII Data guide.

Payload Encryption​

For additional security, Nimbbl supports AES-GCM payload encryption on select APIs. When enabled, request and response payloads are encrypted using a key derived from your access_secret. This is particularly useful for protecting sensitive payment data like card details during transit. Payload encryption is not enabled by default — see the Using Encrypted Payloads guide for setup instructions and sample code.

APIs with encryption or other security requirements are tagged with a Data Security entry in their Quick Reference section, linking to the relevant guide.

Sensitive Data Encryption​

When making direct API calls, sensitive data such as card details and OTP must be RSA-encrypted before submission. Fetch the encryption key from the Get Public Key endpoint and encrypt on the client side. If you use a Nimbbl checkout SDK, this is handled automatically. See the Encrypting Sensitive Data guide for step-by-step instructions.

Getting Started​

The typical integration flow is: Generate Token → Create Order → Initiate Payment → Complete Payment. For a full walkthrough, see the Standard Checkout guide or Choosing Your Integration to pick the right approach for your use case.

Error Handling​

When a request fails, the response includes nimbbl_error_code, nimbbl_consumer_message, and nimbbl_merchant_message fields to help you diagnose and handle the error programmatically.

Rate Limiting​

All APIs are rate-limited. If you exceed the allowed request rate, the API returns a 429 status code with TOO_MANY_REQUESTS error code. Back off and retry after a short delay.

Server Errors​

500 errors return the standard JSON error format. Note that 502 and 504 responses from the infrastructure layer may return HTML instead of JSON — handle these gracefully in your integration.