Download the PHP package nimbbl/nimbbl-sdk without Composer

Nimbbl PHP SDK

Official PHP SDK for integrating with the Nimbbl Payment Gateway API. This SDK provides a simple and intuitive interface to interact with all Nimbbl API endpoints.

Installation

Using Composer (Recommended)

Manual Installation

1. Download the SDK
2. Include the autoloader:

Quick Start

Features

[OK] Complete API Coverage

• Orders API - Create, retrieve orders (uses Order Token)
• Payments API - Initiate, complete payments, resend OTP (Order Token); pre-auth capture / void (Merchant Token)
• Payment Links API - Create, update, manage payment links (uses Order Token)
• Addresses API - Manage customer addresses (uses Order Token)
• Refunds API - Process refunds (full and partial) (uses Merchant Token)
• Transactions API - Transaction enquiry (by order_id, invoice_id, or transaction_id) (uses Merchant Token)
• Checkout Utilities API - Payment modes, banks, wallets, EMIs, offers, card BIN, UPI validation (uses Order Token)

Token Management

The SDK uses two types of tokens:

1. Merchant Token (from generateToken())

   • Used for: Transaction Enquiry, Refund operations
   • Generated from: access_key and access_secret
2. Order Token (from order creation response)
   • Used for: All other operations (Orders, Payments, Payment Links, Addresses, Checkout Utilities)
   • Obtained from: Order creation response ($order['token'])

Token Usage Pattern:

Security Features

• Webhook Signature Verification - Verify webhook authenticity
• Payment Signature Verification - Verify payment responses
• Comprehensive Error Handling - Detailed exception hierarchy

Logging

• Comprehensive Logging - Detailed logging of all API requests and responses
• Multiple Output Channels - Logs to file, PHP error log, and console
• Masked Sensitive Data - Automatically masks API keys and secrets in logs

Framework Agnostic

Works seamlessly with:

• Plain PHP
• Laravel
• CodeIgniter
• Symfony
• Any PHP framework

Documentation

Comprehensive Documentation

Complete documentation for all SDK functionalities is available in the docs/ directory:

• Orders API - Create and retrieve orders
• Payments API - Process payments
• Payment Links API - Manage payment links
• Addresses API - Manage customer addresses
• Refunds API - Process refunds
• Transactions API - Transaction enquiry
• Checkout Utilities API - Checkout helpers
• Authentication API - Token management
• Webhooks - Webhook handling
• Encryption - Data encryption/decryption
• Exception Handling - Error handling patterns
• Logging - Logging configuration

See Documentation Index for a complete overview.

API Clients

Orders API

Note: Orders API uses Order Token (obtained from order creation response).

Payments API

Note: Payments API uses Order Token (obtained from order creation response).

Pre-Authorization: Capture / Void

Available when the sub-merchant is configured with capture_mode=manual (contact Nimbbl to enable). A pre-authorized checkout yields a transaction in the authorized status; you then either capture the held funds or void the hold. Both use the merchant token and are asynchronous — a pending status is normal; confirm the outcome via the capture_success / void_success webhook or Transaction Enquiry.

Capture is terminal — a transaction can be captured or voided, not both. Never fulfil an order on authorized alone; capture first. See example/capture-void-examples.php.

Payment Links API

Addresses API

Refunds API

Note: Refunds API uses Merchant Token (from generateToken()).

Transactions API (Transaction Enquiry)

Note: Transaction Enquiry uses Merchant Token (from generateToken()).

Checkout Utilities API

Note: Checkout Utilities API uses Order Token (obtained from order creation response).

Payment Callback Handling

Note: Encrypted payloads are not enabled by default. Please reach out to [email protected] if you want this functionality.

Always verify the signature first with SignatureVerifier::verifyCallback() on the raw body. It reads the payload's version field (source of truth) and picks the handling automatically — v4 signed envelope (signed with nimbbl_signature), encrypted v4 (AES-GCM decryption authenticates), or legacy v3 per-field — and unwraps the checkout wrappers (globalHandleCheckoutResponse / globalCloseCheckoutModal) for you.

References:

• Standard Checkout Integration Guide - Understanding callbacks
• Encryption/Decryption Guide - Detailed encryption implementation

⚠️ The callback is never the source of truth for the result screen — always confirm via Transaction Enquiry (or the webhook). This matters most for v4, whose callback is minimal.

v4 callback (minimal) — carries only: checkout_status, reason, nimbbl_order_id, nimbbl_transaction_id (may be null), invoice_id, retry, message. There is no transaction/amount/status block — take nimbbl_transaction_id and enquire:

Legacy v3 callback (full payload) — carries the transaction inline; you can read it directly, but still reconcile before fulfilment:

The legacy verifyCallbackSignature(array $payload, $secret) (operates on a pre-parsed array) is retained for backward compatibility, but new integrations should use verifyCallback() on the raw body so v4 signed envelopes are verified correctly.

Encryption/Decryption

For direct encryption/decryption operations, use the Encryption class:

Webhook Handling

Use SignatureVerifier::verifyWebhook() on the raw request body. Like verifyCallback(), it selects v4 signed-envelope vs legacy per-field handling off the version field and returns the parsed payload.

The legacy verifySignature(array $eventData, $secret) is retained for backward compatibility; new integrations should use verifyWebhook() on the raw body.

Error Handling

🧪 Testing

Run Tests

See tests/README.md for the full testing guide (offline vs live, pre-auth capture/void, webhook/callback verification).

Examples

Comprehensive examples are available in the example/ directory:

• index.php - Main examples (all-in-one)
• order-examples.php - Create and retrieve orders
• payments-examples.php - Payment processing examples
• payment-links-examples.php - Payment links examples
• addresses-examples.php - Addresses API examples
• checkout-utilities-examples.php - Checkout utilities examples
• refund-examples.php - Refund examples
• transaction-status.php - Transaction enquiry examples
• webhook-handler.php - Webhook handling
• exception-handling-examples.php - Error handling examples
• encryption-examples.php - Encryption/Decryption examples

See example/README.md for more details.

Project Structure

🔄 Migration from v2 to v3

The SDK now exclusively uses v3 API endpoints. All v2 endpoints and backward compatibility have been removed.

Key Changes

1. API Version: All endpoints now use v3 by default
2. No Version Parameter: apiVersion parameter removed from all methods
3. New API Clients: Added Addresses, Payments, Payment Links, Checkout Utilities, Transaction Status
4. Exception Hierarchy: New exception classes for better error handling
5. Webhook Handling: New Webhook class and WebhookEvent model

Requirements

• PHP >= 7.4
• JSON extension
• cURL extension (for HTTP requests)

🔗 Resources

• API Documentation
• Nimbbl Dashboard
• Support

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For support, email [email protected]

Version: 4.1.0
Last Updated: July 27, 2026