Skip to main content

Integration Steps

Integrate your .NET-based website with our SDK to start accepting payments using the Nimbbl Payment Partner.

Project Structure​

Handy Tips

This integration uses a NuGet package based SDK. If you are not using NuGet, download the latest version of the SDK from GitHub and add the required DLL in your project reference.

Before you proceed:

  • Get the Access Key and Access Secret from the Command Center → Developer Settings → Credentials.
  • Know about the Payment Flow and follow these integration steps:

Integration Overview​

StepDescription
1. Build IntegrationIntegrate with your .NET-based website
2. Test IntegrationTest the integration by making a test payment
3. Go-live ChecklistCheck the go-live checklist

1. Build Integration​

1.1 Install the SDK​

Install the Nimbbl .NET SDK via NuGet:

dotnet add package Nimbbl.Sdk.Rest --version 1.3.5

You can find all versions on NuGet: Nimbbl.Sdk.Rest.

1.2 Configure the SDK​

Create a .env file in your project root for local development:

cp env.example .env

Required Environment Variables​

VariableDescription
NIMBBL_ACCESS_KEYYour Access Key from Command Center
NIMBBL_ACCESS_SECRETYour Access Secret from Command Center
NIMBBL_ACCESS_KEY=your_access_key_here
NIMBBL_ACCESS_SECRET=your_access_secret_here

Optional Environment Variables​

VariableDescriptionDefault
NIMBBL_API_HOSTAPI host URL (do NOT include /api)https://api.nimbbl.tech
NIMBBL_ENABLE_LOGGINGEnable SDK loggingfalse
NIMBBL_DEBUG_LOGGINGEnable debug-level logsfalse
NIMBBL_LOG_FILEPath to log file-
ENCRYPT_PAYLOADEncrypt outgoing request payloads (see supported APIs below)false
Supported APIs for Payload Encryption

When ENCRYPT_PAYLOAD=true, the SDK encrypts request payloads for the following APIs:

For responses, the SDK auto-detects encrypted_response and decrypts it automatically.

For more details on encryption/decryption logic, see Using Encrypted Payloads.

#NIMBBL_API_HOST=https://api.nimbbl.tech
NIMBBL_ENABLE_LOGGING=true
NIMBBL_DEBUG_LOGGING=false
#NIMBBL_LOG_FILE=logs/nimbbl_debug.log
ENCRYPT_PAYLOAD=false

1.3 Register the SDK (Dependency Injection)​

In your Program.cs or Startup.cs, register the SDK with ASP.NET Core's dependency injection:

using Nimbbl.Sdk.Rest.Extensions;

builder.Services.AddNimbbl(
    accessKey: Environment.GetEnvironmentVariable("NIMBBL_ACCESS_KEY")!,
    accessSecret: Environment.GetEnvironmentVariable("NIMBBL_ACCESS_SECRET")!
);

1.4 Create an Order in Server​

Order is an important step in the payment process.

  • An order should be created for every payment.
  • You can create an order using the Nimbbl .NET SDK or by directly calling the Create an Order API. It is a server-side API call.
  • The token received in the response should be passed to checkout. This ties the Order with the payment and secures the request from being tampered.
Using the SDK

The SDK simplifies order creation by handling authentication, request signing, and error handling automatically. The sample code below demonstrates creating an order using the SDK.

1.4.1 Sample Code​

using Nimbbl.Sdk.Rest.Api;
using System.Text.Json;

public class OrdersController : Controller
{
    private readonly NimbblApi _api;
    public OrdersController(NimbblApi api) => _api = api;

    public async Task<IActionResult> CreateOrder()
    {
        // Create order - SDK handles authentication automatically
        var order = await _api.Orders().CreateOrderAsync(new Dictionary<string, object?>
        {
            ["invoice_id"] = $"INV-{Guid.NewGuid():N}",
            ["total_amount"] = 100.0,
            ["currency"] = "INR"
        });

        // Extract order token (used to launch checkout)
        var orderToken = order.TryGetProperty("token", out var ot) && ot.ValueKind == JsonValueKind.String
            ? ot.GetString()
            : null;

        if (string.IsNullOrWhiteSpace(orderToken))
            return BadRequest("Order token not returned from create order.");

        return Ok(new
        {
            order_id = order.TryGetProperty("order_id", out var oid) ? oid.ToString() : null,
            token = orderToken,
            raw = order
        });
    }
}

1.4.2 Request Parameters​

{
  "invoice_id": "inv_asjjeibdhakk49hnek3",
  "total_amount": 2205.00,
  "currency": "INR",
  "amount_before_tax": 2100.00,
  "tax": 105.00,
  "user": {
    "email": "[email protected]",
    "first_name": "Diana",
    "last_name": "Prince",
    "country_code": "+91",
    "mobile_number": "9876543210"
  },
  "shipping_address": {
    "address_1": "1080 Beach Mansion",
    "street": "Magic Beach Drive",
    "landmark": "Opposite Magic Mountain",
    "area": "Elyria",
    "city": "Atlantis",
    "state": "Castalia",
    "pincode": "100389",
    "address_type": "Home"
  },
  "billing_address": {
    "address_1": "1080 Beach Office",
    "street": "Magic Beach Drive",
    "landmark": "Opposite Magic Mountain",
    "area": "Elyria",
    "city": "Atlantis",
    "state": "Castalia",
    "pincode": "100320",
    "address_type": "Other",
    "label": "Sunny Office"
  },
  "order_line_items": [
    {
      "sku_id": "item_2783027490",
      "title": "Best Sliced Alphonso Mango",
      "description": "The Alphonso mango is a seasonal fruit harvested from mid-April through the end of June.",
      "image_url": "https://en.wikipedia.org/wiki/Alphonso_mango#/media/File:Alphonso_mango.jpg",
      "rate": 1050,
      "quantity": 2,
      "amount_before_tax": 2100.00,
      "tax": 105.00,
      "total_amount": 2205.00
    }
  ]
}

For complete request parameters, see Create an Order API.

1.4.3 Response Parameters​

A successful order creation returns the following fields:

{
  "order_id": "o_9yo5wxlLlbJGK6dp",
  "order_date": "2021-04-15 04:34:15.990152",
  "status": "new",
  "invoice_id": "inv_asjjeibdhakk49hnek3",
  "attempts": 0,
  "currency": "INR",
  "amount_before_tax": 2100,
  "tax": 105,
  "total_amount": 2205,
  "user": {
    "email": "[email protected]",
    "first_name": "Diana",
    "last_name": "Prince",
    "country_code": "+91",
    "mobile_number": 9876543210,
    "user_id": "user_78hsjkdhb2482ndk"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjo2LCJzdWJfbWVyY2hhbnRfaWQiOjMsImV4cCI6MTcwNzg5ODk1OSwidHlwZSI6Im1lcmNoYW50IiwiaWF0IjoxNzA3ODk3NzU5LCJpc3MiOiJ1cm46bmltYmJsIiwidG9rZW5fdHlwZSI6InRyYW5zYWN0aW9uIn0.YLpLWonfBIlB8FFBEXQcLt_JA6ymnN0zXANR1J_Bg2M",
  "token_expiration": "2021-01-09T09:49:57.715413",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjo2LCJzdWJfbWVyY2hhbnRfaWQiOjMsImV4cCI6MTcwNzg5ODk1OSwidHlwZSI6Im1lcmNoYW50IiwiaWF0IjoxNzA3ODk3NzU5LCJpc3MiOiJ1cm46bmltYmJsIiwidG9rZW5fdHlwZSI6InRyYW5zYWN0aW9uIn0.YLpLWonfBIlB8FFBEXQcLt_JA6ymnN0zXANR1J_Bg2M",
  "refresh_token_expiration": "2021-01-09T09:49:57.715413",
  "next": [
    {
      "action": "payment_modes",
      "url": "/api/v3/payment-modes"
    },
    {
      "action": "update_order",
      "url": "/api/v3/update-order"
    },
    {
      "action": "resolve_user",
      "url": "/api/v3/resolve-user"
    }
  ]
}

1.5 Add Checkout Options​

The sample app launches checkout via nimbbl_sonic using the order token returned by the Create Order API.

1.5.1 Callback Handler or Callback URL​

You can handle payment responses in two ways:

<script type="module">
  import Checkout from "https://cdn.jsdelivr.net/npm/nimbbl_sonic@latest";

  // token: order token returned from create order API response
  const checkout = new Checkout({ token: "<ORDER_TOKEN>" });

  const options = {
    callback_handler: async function (response) {
      // Send raw callback + (optional) encrypted_response to backend for verification/decryption
      const encryptedResponse = response?.payload?.encrypted_response;
      const res = await fetch("/payment-callback", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          encrypted_response: encryptedResponse || null,
          callback: response
        })
      });
      const data = await res.json();
      console.log("Parsed response:", data.parsed);
    }
  };

  checkout.open(options);
</script>
Handy Tips

1.5.2 Checkout Options​

ParameterRequiredTypeDescription
tokenYesstringOrder token returned from Create Order API
callback_handlerConditionalfunctionHandler function for popup mode (required if not using callback_url)
callback_urlConditionalstringRedirect URL for redirect mode (required if not using callback_handler)

1.6 Handle Payment Callback​

After a payment is completed, Nimbbl sends the payment response to your callback endpoint. You can configure your own callback URL based on your application's routing.

ModeHTTP MethodDescription
RedirectGETResponse sent as response query parameter to your callback_url
PopupPOSTResponse sent in request body to your callback_handler

1.7 Verify Payment Signature​

Watch Out!

This is a mandatory step to confirm the authenticity of the details returned for successful payments.

The SDK provides utility methods for signature verification. In the sample app, the callback controller:

  1. Parses the callback payload
  2. Auto-detects encrypted payloads via encrypted_response
  3. Decrypts (when applicable) and verifies signature
  4. Returns a normalized JSON response

See the sample app's Controllers/HomeController.cs for the full implementation.

For detailed information on signature validation logic and implementation, see Validating Payment Response with Signature.

1.8 Handle Webhooks​

Configure webhooks to receive real-time payment notifications on your server. Email us at [email protected] or contact your dedicated account manager.

Your webhook endpoint should handle POST requests and:

  • Parse the incoming webhook payload
  • Auto-detect encrypted webhooks via encrypted_response
  • Decrypt (when applicable) and verify signature

Enable webhook logging via environment variables:

NIMBBL_ENABLE_LOGGING=true
NIMBBL_DEBUG_LOGGING=false
Implementation Considerations

Webhooks are the primary and most efficient method for event notifications. They are delivered asynchronously in near real-time. For critical user-facing flows that need instant confirmation, supplement webhooks with API verification.

Recommended approach:

  • Rely on webhooks for all automation, which can be asynchronous.
  • If a critical user-facing flow requires instant status, perform an immediate API call to verify the status using Transaction Enquiry API.

2. Test Integration​

After the integration is complete, a Pay button appears on your webpage/app.

Quick Start with Sample App​

Use the official sample app as a reference implementation:

git clone https://github.com/nimbbl-tech/nimbbl-dotnet-sampleapp.git
cd nimbbl-dotnet-sampleapp

cp env.example .env
# Edit .env with your Access Key and Access Secret
dotnet restore
dotnet run

The app runs on http://localhost:5001 (or the port in Properties/launchSettings.json).

Click the Pay button and make a test transaction to ensure the integration is working as expected.

Watch Out!
  • Ensure you have entered your Test Mode credentials in the .env file.
  • No real money is deducted when using test credentials. This is a simulated transaction.

3. Go-live Checklist​

Consider these steps before taking the integration live.

3.1 Accept Live Payments​

Perform an end-to-end simulation of funds flow in Test Mode. Once confident that the integration is working as expected, switch to Live Mode and start accepting payments from customers.

Watch Out!

Ensure you are switching your test credentials with credentials generated in Live Mode.

To switch to Live Mode:

  1. Log in to the Command Center and switch to Live Mode.
  2. Navigate to Developer Settings → Credentials to get Live Mode Access Key and Access Secret.
  3. Replace the Test credentials with Live credentials in your .env file.
  4. Start accepting actual payments.

3.2 Set Up Webhooks​

For webhook configuration and best practices, see Webhooks and Transaction Enquiry.

Sample App & SDK Links​

ResourceLink
SDK (NuGet)Nimbbl.Sdk.Rest
SDK (GitHub)nimbbl-tech/nimbbl-dotnet-sdk
Sample Appnimbbl-tech/nimbbl-dotnet-sampleapp
API ReferenceAPI Reference Introduction
Creating an OrderServer-side order creation for Standard CheckoutAPI ReferenceUnderlying API referenceCommand Center: CredentialsGet access keys for the kit