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. v1.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.

<button id="nimbbl_button">Pay with Nimbbl</button>
<script src="https://api.nimbbl.tech/static/assets/js/checkout.js"></script>
<form name='nimbblpayform' action="verify.php" method="POST">
    <input type="hidden" name="nimbbl_transaction_id" id="nimbbl_transaction_id">
    <input type="hidden" name="nimbbl_signature"  id="nimbbl_signature" >
</form>
<script>
var options = {
        "access_key": "dummy", // Enter the Key ID generated from the Dashboard
        "order_id": order_id, // Enter the order_id from the create-order api
        "callback_handler": function (response) {
            document.getElementById('nimbbl_transaction_id').value = response.nimbbl_transaction_id;
            document.getElementById('nimbbl_signature').value = response.nimbbl_signature;
            document.nimbblpayform.submit();
        },
        "custom": {
            "key_1": "val_1",
            "key_2": "val_2"
        },
    };

var checkout = new NimbblCheckout(options);

document.getElementById('nimbbl_button').onclick = function(e){
    checkout.open(order_id);
    e.preventDefault();
}
</script>

Handle the response​

The way to handle the payment success and failure explained below:

{
    "status": "success",
    "message": "Payment Successful",
    "nimbbl_order_id": "order_RoQ7Zl92G2qqB3rg",
    "nimbbl_transaction_id": "order_RoQ7Zl92G2qqB3rg-20210226111026",
    "nimbbl_signature": hmac_sha256,
    "completion_time": roundtrip
}
ParametersTypeDescription
statusstringTHe status of the transaction
messagestringTransaction message
nimbbl_order_idstringNimbbl unique order id
nimbbl_transaction_idstringNimbbl unique transaction id
nimbbl_signaturestringNimbbl Signature
completion_timeintegerTransaction completed time

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.

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

generated_signature = hmac_sha256(invoice_id + "|" + transaction_id + "|" + total_amount + "|" + currency, <your_secret_key>);

  if (generated_signature == nimbbl_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";

if (empty($_POST['razorpay_payment_id']) === false)
{
    $api = new NimbblApi($keyId, $keySecret);

    try
    {
        // Please note that the Nimbbl order ID must
        // come from a trusted source (session here, but
        // could be database or something else)
        $attributes = array(
            'merchant_order_id' => $_SESSION['merchant_order_id'],
            'nimbbl_transaction_id' => $_POST['nimbbl_transaction_id'],
            'nimbbl_signature' => $_POST['nimbbl_signature'],
            'total_amount' => $_SESSION['total_amount'],
            'currency' => $_SESSION['currency']
        );

        $api->utility->verifyPaymentSignature($attributes);
    }
    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 test cards 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);

Fetch all orders​

$order = $api->order->retrieveMany($options);

Transactions​

Fetch a transaction by Id​

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

Fetch all Transactions​

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

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 all refunds​

$order = $api->refund->retrieveMany($options);

Fetch refund by order_id​

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

Fetch refund by transaction_id​

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