Skip to main content

PHP SDK

The API follows the following practices.

  • Namespaced under Nimbbl\Api.
  • Initialize Nimbbl sdk with access key and secret key.
  • Call $api->class->function() to access the API.
  • All requests and responses are communicated over JSON.
  • Options are passed as an array instead of multiple arguments, wherever possible.

Integration Steps​

Download Nimbbl PHP Server Kit.​

Download the latest file from the releases section on GitHub nimbbl-php-sdk.

  1. v3.0.0 nimbbl-php-sdk.zip
  2. v2.0.0 nimbbl-php-sdk.zip

Add PHP kit to your project file.​

  1. Unzip nimbbl-php-sdk.zip file.
  2. Include Nimbbl.php file in your application.

Initialize Nimbbl PHP SDK​

Get the access key and secret key from Nimbbl and initialize the Nimbbl sdk. Add the below code in your php file.

use Nimbbl\Api\NimbblApi;

$api = new NimbblApi('access_key', 'secret_key');

Integrate Orders API.​

Create order using php server kit function.

Order Creation step is mandatory if you want to automatically capture payments.

Create a file, for example, pay.php and add the API code given below:

    $order_data = array(
            'referrer_platform' => 'referrer_platform',
            'merchant_shopfront_domain' => 'http://example.com',
            'invoice_id' => 'merchant-order-id',
            'order_date' => date('Y-m-d H:i:s'),
            'currency' => 'INR',
            'amount_before_tax' => 100,
            'tax' => 18,
            'total_amount' => 118,
            "user" => [
                "mobile_number" => '9888888888',
                "email" => 'dummy@gmail.com',
                "first_name" => 'Dummy First Name',
                "last_name" => 'Dummy Last Name',
            ],
            'shipping_address' => [
                'area' => 'Goregaon East',
                'city' => 'Mumbai',
                'state' => 'Maharashtra',
                'pincode' => '400063',
                'address_type' => 'home'
            ],
            "order_line_items" => [
                [
                    "title" => "Awesome Product",
                    "quantity" => 1,
                    'uom' => '',
                    'image_url' => 'image_url',
                    'description' => 'Product description',
                    'sku_id' => 'P1',
                    'amount_before_tax' => 100,
                    'tax' => 18,
                    "total_amount" => 118,
                ]
            ],
            'description' => 'This is a test order...',
        );
    $newOrder = $api->order->create($order_data);

Add checkout options.​

Add the checkout options in your project.

Create a file, for example, checkout.php in you folder and add the following code:

For invoking Nimbbl checkout please visit URL.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Your_Site_Title</title>
    <script defer type="module">
      import Checkout from "https://cdn.jsdelivr.net/npm/nimbbl_sonic@latest";
    </script>
  </head>
  <body>
    <script defer type="module">
        import Checkout from "https://cdn.jsdelivr.net/npm/nimbbl_sonic@latest";
    
        const checkout = new Checkout({token:"<order_token>"});

        var options = {
            // pass `callback_url` if you want to open Checkout in the same window.
            callback_url: "https://www.google.com",
            redirect: true
            // callback_handler: function (response) {
            //    alert(response);
            // },

            // only if you want to enforce a specific payment method
            // payment_mode_code: string,
            // bank_code: string,
            // wallet_code: string,
            // payment_flow: string,
            // upi_id: string,
            // upi_app_code: string,
        };

        checkout.open(options);
      </script>
  </body>
</html>

Handle the response​

The final step in completing the client integration is capturing the response and sending it to your server

Checkout with Handler Function​

If you used the sample code with the handler function, then: 

"handler": function (response){
    /**
     *  send  the response to your server for processing
     * /
}

For sample response structure, refer to the URL

Checkout with Callback URL​

When you use a Callback URL with redirect true, you will redirected to that callback_url with a base64 encoded payload response appended to it.

callback_url?response=base64_payload

You will need to decode the base64 payload. To learn how to decode the payload, you can refer here. The decoded response will need to be sent to your server.

Verify payment signature.​

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

  1. Create a signature in your server using the following attributes:

    • invoice_id : Use the invoice_id of the order that is generated on your server.
    • transaction_id : Transaction Id returned by Nimbbl for the payment
    • access_secret : Available in your server. The access_secret that was generated from the Dashboard.
    • total_amount : Available in your server. The order total amount that was generated on your server which should be a float value upto 2 decimal.
    • currency : Available in your server. The order currency that was generated from the Dashboard.
    • status : Use the status in the transaction object returned by Nimbbl in the response.
    • transaction_type : Use the transaction_type in the transaction object returned by Nimbbl in the response

  2. Use the SHA256 algorithm to construct a HMAC hex digest as shown below:

If the signature_version returned in the Webhook/Callback is v3 then verify the signature using the logic mentioned below:

generated_signature = hmac_sha256(invoice_id + "|" + transaction_id + "|" + transaction_amount + "|" + transaction_currency + "|" + status + "|" + transaction_type, <your_secret_key>);

  if (generated_signature == signature) {
    payment is successful
  }
  1. If the signature you generate on your server matches the nimbbl_signature returned to you by the checkout, the payment received is from an authentic source.
require('nimbbl-php/Nimbbl.php');
use Nimbbl\Api\NimbblApi;
use Nimbbl\Api\NimbblError;

$success = true;

$error = "Payment Failed";

    $api = new NimbblApi($keyId, $keySecret);

    try
    {
        // Please note that the Nimbbl order ID must
        // come from a trusted source and the webhook
        // data is to be passed as is.
        $api->utility->verifyPaymentSignature($webhook_data, $order);
    }
    catch(NimbblError $e)
    {
        $success = false;
        $error = 'Nimbbl Error : ' . $e->getMessage();
    }

if ($success === true)
{
    $html = "<p>Your payment was successful</p>
             <p>Payment ID: {$_POST['nimbbl_transaction_id']}</p>";
}
else
{
    $html = "<p>Your payment failed</p>
             <p>{$error}</p>";
}

echo $html;

Test Integration​

After the integration is complete, test the integration to make sure it is working as expected. You can test using testing credentials and verify the payment status from Nimbbl.

Sample Code​

Initialization​

use Nimbbl\Api\NimbblApi;

$api = new NimbblApi('access_key', 'secret_key');

Generate API Keys​

You should have registered with Nimbbl and have received your test access key & secret key. If you haven’t registered with Nimbbl, please sign-up here and our team will reach out to you.

Orders​

Create an order​

 $order_data = array(
            'referrer_platform' => 'referrer_platform',
            'merchant_shopfront_domain' => 'http://example.com',
            'invoice_id' => 'merchant-order-id',
            'order_date' => date('Y-m-d H:i:s'),
            'currency' => 'INR',
            'amount_before_tax' => 100,
            'tax' => 18,
            'total_amount' => 118,
            "user" => [
                "mobile_number" => '9888888888',
                "email" => 'dummy@gmail.com',
                "first_name" => 'Dummy First Name',
                "last_name" => 'Dummy Last Name',
            ],
            'shipping_address' => [
                'area' => 'Goregaon East',
                'city' => 'Mumbai',
                'state' => 'Maharashtra',
                'pincode' => '400063',
                'address_type' => 'home'
            ],
            "order_line_items" => [
                [
                    "title" => "Awesome Product",
                    "quantity" => 1,
                    'uom' => '',
                    'image_url' => 'image_url',
                    'description' => 'Product description',
                    'sku_id' => 'P1',
                    'amount_before_tax' => 100,
                    'tax' => 18,
                    "total_amount" => 118,
                ]
            ],
            'description' => 'This is a test order...',
        );
    $newOrder = $api->order->create($order_data);

Fetch an order by Id​

$order = $api->order->retrieveOne($order_id);

Transactions​

Fetch a transaction by Id​

$order = $api->transaction->retrieveOne($transaction);

Fetch a transaction by order_id​

$order = $api->transaction->retrieveTransactionByOrderId($options);

Refunds​

Create a refund​

$attribute = array(
    'order_id' => 'order_aQA3j4bxxeQKj72N',
    'transaction_id' => 'order_aQA3j4bxxeQKj72N-20210706145203'
);
$order = $api->refund->initiateRefund($attribute);

Fetch refund by Id​

$order = $api->refund->retrieveOne($refund_id);

Fetch refund by order_id​

$order = $api->refund->retrieveRefundByOrderId($order_id);

Fetch refund by transaction_id​

$order = $api->refund->testRetrieveRefundByTxnId($transaction_id);