Web Integration

Gokwik provides you RTO protection and empowers you to provide a seamless shopping experience to your customers. Gokwik integrates with your website and supports your customers to place orders via Cash on Delivery and UPI options. The following document has essential features for integrating your website with Gokwik. The steps are:

Step 1: Create an order from the backend

Sandbox Endpoint: https://sandbox.gokwik.co/v1/order/create

Request Data:

Header

NameTagsDescription
AppidMandatory StringYOUR APPID is different for test and production
AppsecretMandatory StringYOUR APPSECRET is different for test and production
Content-TypeMandatory StringApplication/json

Body

SL no.ObjectParameterTypeDescription
1orderidMandatory Stringorder id which will be unique for all future communication as moid. if you have only cart id then you can send cart id in "id" as well as in "cart_id"
2ordercart_idOptional String
3orderstatusMandatory StringPending would be first order status
4ordersubtotalMandatory Float (2 digits after decimal)total cart value before applying discount
5ordertotal_line_itemsMandatoryInteger number of unique sku's in the order
6ordertotal_line_items_quantityMandatoryInteger total number of items
7ordertotal_tax MandatoryFloat (2 digits after decimal)total calculated tax
8ordertotal_shippingMandatoryFloat (2 digits after decimal)total shipping charges
9ordertotal_discount MandatoryFloat (2 digits after decimal)total discount amount on order value
10ordertotal MandatoryFloat (2 digits after decimal) total = subtotal + total_tax + total_shipping - total_discount(discount due to promocode or cashback discount )
11orderpromo_codeMandatory Stringpromo code applied
12ordersourceMandatory StringExample: organic/facebook/instagram/others
13ordercustomer_ipMandatory StringExample: "103.82.80.57"
14ordercustomer_user_agentMandatory StringExample : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.16; rv:86.0) Gecko/20100101 Firefox/86.0"
15payment_detailsmethod_idMandatory Stringeither "upi" or "cod" both in small case
16line_itemsproduct_idVarchar id of the product, which is used to list the product on the store
17line_itemsline_item_idVarchar line_item id which type of product
18line_itemsvariant_idVarchar variation if for the product
19line_itemsnameStringname of the product
20line_itemsskuMandatory Stringsku of the product
21line_itemspriceMandatory Float (2 digits after decimal)maximum retail price of that product
22line_itemsquantityMandatory Integerquantity of the product
23line_itemssubtotalFloat (2 digits after decimal)Sale price of the products in this line item
24line_itemstotalMandatory Float (2 digits after decimal)total of all the products in line_item after discount, tax and shipping
25line_itemstaxFloat (2 digits after decimal)calculated value for tax
26line_itemsproduct_url Stringurl of the product page
27line_itemsproduct_thumbnail_urlStringurl of the thumbnail image of the product
28productany fieldJsonObjecthere you need to add product more details like colour, size, etc..
29shipping_addressfirst_nameMandatory Stringfirst name of user
30shipping_addresslast_nameMandatory Stringlast name of user
31shipping_addresscompanyStringcompany name of user
32shipping_addressaddress_1Mandatory Stringaddress line 1
33shipping_addressaddress_2Stringaddress line 2
34shipping_addresscityOptional Stringdelivery city
35shipping_addressstateMandatory Stringdelivery state
36shipping_addresspostcodeMandatory Stringdelivery postcode
37shipping_addressemailStringemail id of user
38shipping_addressphoneVarchar Limit10phone number of user
39billing_addressfirst_nameMandatory Stringfirst name of user
40billing_addresslast_nameStringlast name of user
41billing_addresscompanyStringcompany name of user
42billing_addressaddress_1Mandatory Stringaddress line 1
43billing_addressaddress_2Stringaddress line 2
44billing_addresscityMandatory Stringaddress city
45billing_addressstateMandatory Stringaddress state
46billing_addresspostcodeMandatory Stringaddress postcode
47billing_addressemailStringemail id of user
48billing_addressphoneVarchar limit10phone number of user
COUNT 48
Curl Example:
Copy
curl --location --request POST 'https://sandbox.gokwik.co/v1/order/create' --header 'appid: YOUR APPID' --header 'appsecret: YOUR APPSECRET' --header 'Content-Type: application/json' --data-raw '{
    "order": {
        "id": "gyug78879sdf",
        "cart_id": "tuyguy6758686sdf",
        "status": "pending",
        "subtotal": "800",
        "total_line_items": "1",
        "total_line_items_quantity": "1",
        "total_tax": "160",
        "total_shipping": "50.0",
        "total_discount": "100",
        "total": "910",
        "promo_code":"XYZ_20",
        "source":"organic",
        "payment_details": {
            "method_id": "cod"
        },
        "billing_address": {
            "first_name": "Test",
            "last_name": "Shop",
            "company": "Test",
            "address_1": "Test",
            "address_2": "",
            "city": "Delhi",
            "state": "DL",
            "postcode": "110092",
            "country": "IN",
            "email": "xyz@exampal.com",
            "phone": "1234567890"
        },
        "shipping_address": {
            "first_name": "",
            "last_name": "",
            "company": "",
            "address_1": "",
            "address_2": "",
            "city": "",
            "state": "",
            "postcode": "",
            "country": "",
            "email": "xyz@exampal.com",
            "phone": "1234567890"
        },
        "customer_ip": "103.82.80.57",
        "customer_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.16; rv:86.0) Gecko/20100101 Firefox/86.0",
        "line_items": [{
            "product_id": "15",
            "line_item_id" : "id_of_line_item",
            "variant_id": "0",
            "product": {},
            "name": "Beanie",
            "sku": "",
            "price": 1000,
            "quantity": 1,
            "subtotal": "800",
            "total": "800",
            "tax": "0",
            "product_url": "",
            "product_thumbnail_url": ""
        }]
    }
}'
Copy
{
  "statusCode": 200,
  "statusMessage": "Order Placed",
  "data": {
        "request_id": "3b7f69c9-75e4-4294-919f-7a1d7b0a3592",
        "gokwik_oid": "KWIKQKXEL9PQ0165308",
        "order_status": "pending",
        "total": "910.0000",
        "moid": "gyug78879sdf",
        "mid": "gh067jgklm4f5i2",
        "phone": "1234567890",
        "order_type": "cod"
    }
}
Copy
{
  "statusCode": 201,
  "statusMessage": "Order already exist!"
}
Copy
{
  "statusCode": 404,
  "statusMessage": "Merchant not registered!"
}
Copy
{
  "statusCode": 400,
  "statusMessage": "Order Failed"
}
Copy
{
  "statusCode": 500,
  "statusMessage": "Oops!! Something went wrong"
}

Step 2: Initiate Payment

Copy
 //Please ensure that the following script tag is loaded in <head> tag.
<script src="https://checkout.gokwik.co/integration.js"></script>
    let merchantInfo = {
    order_type:"upi",
    mid:"gh065rxkjvv200w",
    moid:"4120",
    environment: "production",
    request_id: "01c47427-82d1-41c5-ace5-7b8735f75a1d",
    gokwik_oid: "KWIKGSJHNG0B3818197",
    css: {
	primaryColor:"#f08080",
	secondaryColor:"#ffa07a"
	},
	 showModal: true,
    }

// If the user is being redirected and the pop up has to open without any actions
    window.onload = (event) => {
        gokwikSdk.initPayment(merchantInfo);
    };

// If the pop up has to be opened on some action (eg. button click)
    gokwikSdk.initPayment(merchantInfo);


// If Integration.js is loaded dynamically (eg. using createElement),
ensure gokwikSdk function is invoked only after the script has finished loading

Note:

environment will be "sandbox" or "production"

Note:

For COD Orders, Do this on success_page/thank_you page.

CallBack Listener
Copy
gokwikSdk.on(‘failure’,(data)=>{
console.log(‘order failed’, JSON.stringify(data))
    /* sample response object
    1.  {
            type: ”ORDER_CANCELLED”
            gokwik_oid: ‘111’,
            order_type: "upi"
        }
    2.  {
            type: ”WRONG_ORDER_OBJECT”
            missingParams
        }
    */

    //check can be added like
    if (data.type === “WRONG_ORDER_OBJECT”) {
        // handler
    }

    if (data.type === “ORDER_CANCELLED”) {
        // handler
    }

})
Copy
gokwikSdk.on('success',(data)=>{
//Check order status from your backend if it is paid then navigate to thank you page. In case of status is not paid then you should call payment verify API from your backend.
console.log('order success',JSON.stringify(data))
gokwikSdk.close(); // for closing dialog
})
To close popup
Copy
gokwikSdk.close()

Close callback
gokwikSdk.on(“modal_closed”,()=>{console.log('popup closed')})

Step 3: Payment Notification Callback

Payment Notification webhook:

This webhook would be provided by the merchant which will be used to notify any of the payments against the order. This will mark order paid at merchant backend. the data which we will send on this webhook is as below.

Copy
curl --location --request POST 'merchant_callback_url' --header 'appid: YOUR APPID' --header 'appsecret: YOUR APPSECRET' --header 'Content-Type: application/json'
 {
    "request_id": "Your order request id",
    "gokwik_oid": "Your order Gokwik id",
    "moid": "Your order id",
    "transaction_id": "Transaction id"
}

Note:

Call Payment Verify API to Manually verify Payment.

Payment Verify Request
Copy
curl --location --request POST 'https://sandbox.gokwik.co/v1/payment/verify' --header 'appid: {{app_id}}' --header 'appsecret: {{app_secret}}' --header 'Content-Type: application/json' --data-raw '{
    "gokwik_oid": "KWIKMG1DLW3Q5548364",
    "total": "54.00"
}'

Response:

Copy
{
"statusCode": 200,
"statusMessage": "Payment Success",
"data": {
    "transaction_id": 722,
    "total":"36.00",
    "gokwik_oid": "KWIKOIO8WXO6013589"
 }
}
Copy
{
  "statusCode": 202,
  "statusMessage": "Payment pending"
}
Copy
{
  "statusCode": 404,
  "statusMessage": "Order not found"
}
Copy
{
  "statusCode": 404,
  "statusMessage": "Transaction not found or initiated"
}
Copy
{
  "statusCode": 404,
  "statusMessage": "Merchant not found"
}
Copy
{
  "statusCode": 400,
  "statusMessage": "Oops!! Something went wrong"
}
Copy
{
  "statusCode": 400,
  "statusMessage": "Missing headers"
}

Step 4: Update Order

Outside web-flow

This endpoint would be used to relay all the order-related status updates mentioned below.

Sample Order Statuses:
  • pending = order has been created and it usually before payment
  • processing = order has been moved to processing status usually post payment confirmation
  • shipped = order has been shipped or dispatched from the warehouse
  • in-transit = order is on the way to the customer
  • delayed = order has been delayed by expected ETA
  • rto = order returned to origin
  • ofd = out for delivery
  • cancelled = order got cancelled by either admin or user
  • returned = order has been returned from user not RTO
  • delivered = order has been delivered to end user
  • completed = order cycle has been completed

Endpoint: https://sandbox.gokwik.co/v1/order/update

Request Data:

Header

NameTagsDescription
AppidMandatory StringYOUR APPID is different for test and production
AppsecretMandatory StringYOUR APPSECRET is different for test and production
Content-TypeMandatory StringApplication/json

Body

SL no.ParameterTypeDescription
1moidMandatory StringMerchant order id
2cart_idOptional StringMerchant cart id
3gokwik_oidMandatory StringThis you will get in order create api response
4order_statusMandatory StringStatus of order as mention in sample order statuses or whatever maintain at our end
5 variant_idMandatory arrayExample :["item2", "item3"],
6typeMandatoryInteger Example :"merchant"
7awb_numberMandatory StringShipper's tracking number
8awb_statusMandatory StringItem tracking status
9shipping_providerMandatory StringShipper's Name
10order_noteMandatory Stringany note related to item it could be string
COUNT 10
Curl Example:
Copy
curl --location --request POST 'https://sandbox.gokwik.co/v1/order/update' --header 'appid: YOUR APPID' --header 'appsecret: YOUR APPSECRET' --header 'content-type: application/json' --data-raw '{
 "moid": "order_id_of_merchant",
 "cart_id": "shopping_cart_id",
 "gokwik_oid":"KWIKOIO8WXO6013589",
 "order_status":"shipped",
 "variant_id":["item2", "item3"],
 "type":"merchant",
 "awb_number": "ABCDFRT",
 "awb_status": "",
 "line_item_id" : "lid1",
 "shipping_provider":"Bluedart",
 "order_note":""
}'

Response:

Copy
{
  "statusCode": 200,
  "statusMessage": "Order status changed by customer"
}
Copy
{
  "statusCode": 404,
  "statusMessage": "Merchant not registered!"
}
Copy
{
  "statusCode": 400,
  "statusMessage": "Oops!! Something went wrong"
}
Copy
{
  "statusCode": 405,
  "statusMessage": "unknown field values"
}

BASE URL: base URL for test and production environment

Test Server: https://sandbox.gokwik.co

Production Server: https://api.gokwik.co

Other important info::

appid: YOUR APPID.

appsecret: YOUR APPSECRET

Above two things you need to send in order create API that you will get once you register with GoKwik https://dashboard.gokwik.co/