API Integration

To use Thirdwatch on your custom-build website, you will have to integrate with the Thirdwatch Orders API. This API contains all required customer and order information.

Gateway URL#

The Razorpay API Gateway URL is https://api.razorpay.com/v1. You need to include this before each API endpoint to make API calls.

API Authentication#

All Thirdwatch APIs are authenticated using your API key. Every API request must contain the API Key X-THIRDWATCH-API-KEY in the header.

Every API request should also contain your user_id. If this is not available, you can alternatively provide a session_id value.

Your API key is sent to you via email when you activate your account. You can also find this on the Dashboard, Settings → General. Refer to the short animation below for more information.

Device and User Information#

You can collect customer information by creating a device fingerprint.

A fingerprint is a unique hashed string identifier that is generated by combining the hashed values of several device parameters. Thirdwatch’s Fingerprint SDK generates this identifier for the user and passes it to Thirdwatch.

The Fingerprint is generated using parameters such as the user agent, plugins installed, webGL rendering information, device OS and fonts installed. Using these parameters, our unique fingerprinting algorithm generates the hashed string identifier.

This helps better identify customers as the device parameters remain unchanged irrespective of the browsing platform used, cookies and other application-level identifiers.

To add device fingerprinting to your website, paste the below script on your webpage, just after the opening tag. This script should be added to the page that is accessed by your customer. For example, if you want to track three different web pages then paste the below script on each webpage, just after the opening tag.

Pass device and user information using Thirdwatch Orders API:
In case you do not want to pass device details to Thirdwatch via your front-end, you can do so using the Thirdwatch Orders API.

 Device Fingerprinting JavaScript
Copy< script
  id="thirdwatch"
  src="https://cdn.thirdwatch.ai/tw.min.js"
  data-user-id="user-id"
  data-app-secret="app-secret"
  data-is-track-pageview="true"
  data-session-cookie-name="default"
  data-session-id-value="session-123"
  defer
></script>

Parameters required by the script:

data-user-idmandatory

Data type string. The unique user id at your end. This can be an email id or primary key in the database. In the case of a guest user, you can insert the session ID here.

data-app-secretmandatory

Data type string. The unique App secret generated for you by Thirdwatch.

data-is-track-pageviewoptional

Data type boolean. Possible values:

true (default) - The URL on which this script is running is sent to Thirdwatch.
false - The URL is not captured.

data-session-cookie-nameoptional

Data type string. The cookie name where you are saving the unique session id. We will pick the session ID by reading its value from the cookie name.

data-session-id-valueoptional

Data type string. In case you are not passing data-session-cookie-name, you can pass the session ID directly in this parameter. In absence of both data-session-cookie-name and data-session-id-value, our system will generate a session ID.

Orders API#

Thirdwatch API collects information associated with the life cycle of an order to help you make decisions. You can use the below endpoint to pass data of the events associated with the customer and their purchases during the time of the transaction.

/thirdwatch/orders

 Request Example Response
Copycurl -X POST https://api.razorpay.com/v1/thirdwatch/orders \
-H 'X-THIRDWATCH-API-KEY: <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
  "device":{
    "ip":"192.178.0.1",
    "session_id":"5f7dok65iif989fwrmn88er47gk834",
    "user-agent":"Mozilla/5.0 (Linux; <Android Version>; <Build Tag etc.>)AppleWebKit/<WebKit Rev> (KHTML, like Gecko) Chrome/<Chrome Rev> MobileSafari/<WebKit Rev>"
  },
  "user":{
    "id":"AsXcYnkERrjb",
    "created_at":"1578924272676",
    "email":"gaurav.kumar@example.com",
    "first_name":"Gaurav",
    "last_name":"Kumar",
    "contact":"+919876543210",
    "first_purchase":true,
    "email_verification":"verified",
    "contact_verification":"verified"
  },
  "order":{
    "id":"Axn167SnweX",
    "created_at":"1578924272676",
    "amount":"1560000",
    "currency":"INR",
    "prepaid":true,
    "items":[
      {
        "id":"XQF1576BGY",
        "title":"Office Bag",
        "amount":"50000",
        "currency":"INR",
        "brand":"Renegade X",
        "category":"Apparels > Men > Bag",
        "quantity":10,
        "is_onsale":true,
        "sku":"167380XBGEB"
      }
    ],
    "shipping_address":{
      "name":"Gaurav Kumar",
      "phone":"+919876543210",
      "line1":"221B Bakery Street",
      "line2":"14th Main Road, 3rd Cross",
      "city":"Bengaluru",
      "state":"Karnataka",
      "country":"IN",
      "postal_code":"560069",
      "type":"home"
    },
    "promotions":[
      {
        "id":"XPY100",
        "status":"applied",
        "amount":"100",
        "type":"discount",
        "currency":"INR"
      }
    ],
    "payment":{
      "id":"Axf26ns78G",
      "status":"success",
      "gateway":"Razorpay",
      "amount":"15600",
      "currency":"INR",
      "method":"card",
      "bank":"YESB",
      "wallet":"",
      "card":{
        "last4":"6600",
        "type":"credit",
        "issuer":"YESB",
        "international":false,
        "name":"Gaurav Kumar",
        "iin":"456078",
        "expiry_year":"23",
        "expiry_month":"11"
      }
    }
  }
}'
Copy{
  "success": true,
  "message": "Order details processed successfully."
}

Request Parameters#

device

Details of the device used to place the order.

Note:
If device details are passed via your front-end, all parameters in this array can be passed as empty strings.

ipmandatory: Data type string. The IP address from where the order is being placed. For example, 192.178.0.1.
session_idmandatory: Data type string. The unique identifier for the session.
user-agentmandatory: Data type string. Details of the browser being used to place the order. For example, Mozilla/5.0.

user

This entity contains information related to the customer making the purchase. This information is important to understand the fraudulent behavior of delinquent customers.

idmandatory

Data type string. Your customer’s account ID according to your system. This field is case-sensitive. For example, AsXcYnkERrjb.

created_atmandatory

Data type string. The Unix timestamp in milliseconds when the customer account was created in your system. For example, 1578487238129.

emailmandatory

Data type string. The customer's email address. For example, gaurav.kumar@example.com. Note: If the customer’s email is also their account ID in your system, set both the user_id and email fields to their email address.

first_namemandatory

Data type string. The customer's first name. For example, Gaurav.

last_namemandatory

Data type string. The customer's last name. For example, Kumar.

contactmandatory

Data type string. The customer's phone number. For example, 9123456789.

first_purchasemandatory

Data type boolean. Set to true if the customer is a first-time buyer.

email_verificationmandatory

Data type string. Status of email verification. Possible values:

unverified (default)
pending
verified

contact_verificationmandatory

Data type string. Status of phone number verification. Possible values:

unverified (default)
pending
verified

order

Details of the order being created.

idmandatory

Data type string. A unique identifier for the order created in your system. For example, Axn167SnweX.

created_atmandatory

Data type string. The Unix timestamp in milliseconds when the order was created in your system. For example, 1578487238129.

amountmandatory

Data type string. The order amount in the currency subunit. For example, if the order amount is ₹15,600 pass 1560000.

currencymandatory

Data type string. The 3-letter ISO currency code for the order amount. For example, INR.

prepaidmandatory

Data type boolean. Pass true if the order is prepaid.

item

This entity comprises of an array of items that contain item details such as amount, currency, brand, category, and quantity.

idmandatory: Data type string. A unique identifier for an item created in your system. Use the same ID that you would use to look up items on your website's database. For example, XQF1576BGY.
titlemandatory: Data type string. The item's name. For example, Awesome bag to impress your friends.
amountmandatory: Data type string. The item amount in the currency subunit. For example, if the order amount is ₹15,600 pass 1560000.
currencymandatory: Data type string. The 3-letter currency code for the item amount. For example, INR.
brandmandatory: Data type string. The brand name of the item. For example, Office bags.
categorymandatory: Data type string. The category the item is listed under in your business. For example, "Office bags", "man > bags".
quantitymandatory: Data type integer. Quantity for the item. For example, 4.
is_onsalemandatory: Data type boolean. Set to true if the item is on sale.
skuoptional: Data type string. The stock-keeping unit ID (SKU) for the item, if available. For example, 167380XBGEB.

shipping_address

Address where the order is to be shipped.

namemandatory

Data type string. The full name associated with the address. For example, Gaurav Kumar. Concatenate first name and last name together if you collect them separately in your system.

phonemandatory

Data type string. The phone number associated with this address. Provide the phone number as a string starting with the country code. For example, +919123456789.

line1mandatory

Data type string. The first line of the shipping address. For example, 221B Bakery Street.

line2mandatory

Data type string. The second line of the address. For example, 14th Main Road, 3rd Cross.

citymandatory

Data type string. The city or town name. For example, Bengaluru.

statemandatory

Data type string. The state where the address is to be shipped. For example, Karnataka.

countrymandatory

Data type string. The 2-letter ISO country code where the order is to be shipped. For example, IN for India.

postal_codemandatory

Data type string. The postal code where the order is to be shipped. For example, 560666.

typemandatory

Data type string. The type of address. Possible values:

home
office
other

promotions

An array of promotions applied to the order.

idoptional

Data type string. The unique identifier for the coupon code in your system. For example, ADbb.

statusoptional

Data type string. Use this to pass both successful and failed attempts to Thirdwatch when using a promotion. This may be useful in spotting potential abuse. Possible Values:

applied
failed

typeoptional

Data type string. Type of promotion. Possible values:

discount
cashback
store_credit
voucher

amountoptional

Data type string. The amount or credits the promotion is worth in the currency subunits. For example, if the promotion is worth ₹50 pass 5000.

currencyoptional

Data type string. The 3-letter ISO currency code for the amount. For example, INR.

payment

This entity holds information about the payment made against the Order.

idmandatory

Data type string. The unique identifier for the payment. This is important to track transactions and to link different parts of the same transaction, such as a refund, together.

statusmandatory

Data type string. The status of the payment. Possible values:

pending
success
failure

gatewaymandatory

Data type string. The gateway used for the transaction. For example, razorpay.

amountmandatory

Data type string. The amount for the payment in the currency subunits. For example, if the payment is worth ₹7,500 pass 750000.

currencymandatory

Data type string. The 3-letter ISO currency code for the payment amount. For example, INR.

methodmandatory

Data type string. The method used to make the payment. Possible values:

card
wallet
upi
netbanking
cod
fund_transfer

bankoptional

Data type string. Name of bank from which the payment was made. For example, State Bank of India.

walletoptional

Data type string. Name of wallet from which the payment was made. For example, amazonpay.

card

Details of the card used to make the payment.

last4optional

Data type string. Last 4 digits of the card. For example, 0305

typeoptional

Data type string. The type of card used to make the payment. Possible values:

debit
credit
gift
prepaid

issueroptional

Data type string. The name of the bank issuing the card. For example, State Bank of India.

internationaloptional

Data type boolean. Pass true if the card has been issued outside India. Defaults to false.

iinoptional

Data type string. First 6 digits of the card number. For example, 305619.

expiry_monthoptional

Data type string. The expiry month for the card in the MM format. For example, if the card expires in October, pass 10.

expiry_yearoptional

Data type string. The expiry year for the card in the YY format. For example, if the expiry year is 2022, pass 22.

nameoptional

Data type string. The name of the cardholder. For example, Gaurav Kumar.

Retrieve Analyzed Results#

Once you create an order, Thirdwatch begins to analyze the data. This is an asynchronous process on Thirdwatch’s end and lasts for less than 200 ms. You can retrieve the outcome of the analysis using the:

Score Postback URL
This involves you listening to a webhook response.
Score API
This requires you to manually fetch the order score.

Configure Score Postback URL#

To listen to the response, you can configure your own Score Postback URL on the Thirdwatch Dashboard.

Action Required:
You need to configure the Score Postback URL on your server. Thirdwatch simply sends the score postback to this URL for your consumption.

To add a Score Postback URL:

Log into the Dashboard.
Navigate to Settings → Configure.
Add the score postback URL in the Score Postback URL field.

Refer to the short animation below for more information.

Webhook Payload#

 Score Postback Webhook Payload
Copy{
  "order_id":"Axn167SnweX",
  "user_id":"AsXcYnkERrjb",
  "order_timestamp":"1578924272676",
  "score":82,
  "flag":"red",
  "reasons":[
    {
      "name":"numOfFailedTransactions",
      "display_name":"Number of failed transactions",
      "flag":"green",
      "value":"0"
    },
    {
      "name":"accountAge",
      "display_name":"Account age",
      "flag":"red",
      "value":"0"
    },
    {
      "name":"numOfOrderSameIp",
      "display_name":"Number of orders from same IP",
      "flag":"red",
      "value":"11"
    }
  ]
}

Payload Parameters#

order_id

Data type string. This has to be the same as the order_id used in the Thirdwatch Orders API. For example, Axn167SnweX.

user_id

Data type string. The ID of the user who placed the order. This should be the same as the user_id used in the Thirdwatch Orders API. For example, AsXcYnkERrjb.

order_timestamp

Data type string. The Unix timestamp in milliseconds when the order was created. For example, 1578924272676.

score

Data type integer. The probability score calculated by Thirdwatch systems on the overall confidence of the prediction. A higher probability score indicates that the order is more likely to be a fraud order.

flag

Data type string. Possible values:

Red - Indicates the potential of fraud. This needs to be further investigated by you.
Green - Indicates the order can be shipped to the customer.

reasons

Data type array. List of reasons why Thirdwatch has flagged an order as red. This also takes into account any custom rule that you set up on the Dashboard.

name: Data type string. The name of the rule defined by you on the Dashboard.
display_name: Data type string. The display name of the rule defined by you on the Dashboard.
flag: Data type string. The nature of flagging by the rule.
value: Data type string. The level of impact your custom rule had on the order being flagged.

Score API#

You can fetch the outcome of the analysis along with an up-to-date customer trust score using the below endpoint.

/thirdwatch/score?order_id=:id

 Request Response
Copycurl -X GET https://api.razorpay.com/v1/thirdwatch/score?order_id=Axn167SnweX \
-H 'X-THIRDWATCH-API-KEY: <API_KEY>' \
Copy{
  "order_id":"Axn167SnweX",
  "user_id":"AsXcYnkERrjb",
  "order_timestamp":"1578924272676",
  "score":82,
  "flag":"red",
  "reasons":[
    {
      "name":"numOfFailedTransactions",
      "display_name":"Number of failed transactions",
      "flag":"green",
      "value":"0"
    },
    {
      "name":"accountAge",
      "display_name":"Account age",
      "flag":"red",
      "value":"0"
    }
  ]
}

Response Parameters#

order_id

Data type string. This has to be the same as the order_id used in the Thirdwatch Orders API. For example, Axn167SnweX.

user_id

Data type string. This has to be the same as the user_id used in the Thirdwatch Orders API. For example, AsXcYnkERrjb.

order_timestamp

Data type string. The Unix timestamp in milliseconds when the order was created. For example, 1578924272676.

score

Data type integer The probability score calculated by Thirdwatch systems on the overall confidence of the prediction. A higher probability score indicates that the order is likely to be fraudulent.

flag

Data type string. Possible values:

Red - Indicates potential of fraud. This needs to be further investigated by you.
Green - Indicates that the order can be shipped to the customer.

reasons

Data type array. List of reasons why Thirdwatch has flagged an order as red. This also takes into account any custom rule that you set up on the dashboard.

name: Data type string. The name of the rule defined by you on the Dashboard.
display_name: Data type string. The display name of the rule defined by you on the Dashboard.
flag: Data type string. The nature of flagging by the rule.
value: Data type string. The impact of the rule on the flagging the order.

Synchronize Actions and Order Status with Thirdwatch#

You can synchronize actions taken on your server with the decisions taken via Thirdwatch. For example, you might have separate Fraud Prevention and Shipping Teams. The Fraud Prevention Team might work on the Thirdwatch Dashboard, while the Shipping Team works on your server.

There are two APIs for this.

Action API
Using this API, you can pass actions taken on your server to Thirdwatch. For example, if you update an order on your server, you can use this API to update the order on Thirdwatch.
Action Postback API
Using this API, you can sync actions (such as cancelling an order or updating an order) taken on the Thirdwatch Dashboard with your server. For example, cancelling an order on the Thirdwatch Dashboard will cancel the order on your server.
Address Update API
Using this API, you to sync changes to the shipping address made on the Thirdwatch Dashboard with your server.

Action API#

You can use the below API to sync information between your server and the Thirdwatch Dashboard.

/thirdwatch/clientaction

 Request200 OK
Copycurl -X POST https://api.razorpay.com/v1/thirdwatch/clientaction \
-H 'X-THIRDWATCH-API-KEY: <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
      "order_id":"Axn167SnweX",
      "action_type":"approved",
      "message":"Accepted after review"
    }'
Copy{
  "success": true,
  "msg": "Action submitted successfully."
}

Request Parameters#

order_idmandatory

Data type string. This has to be the same as the order_id used in the Thirdwatch Orders API. For example, Axn167SnweX.

action_typemandatory

Data type string. The action taken on the dashboard. Possible values:

approved
on_hold
declined

messageoptional

Data type string. A user-entered message entered while performing an action on your server. For example, Accepted after review.

Action Postback API#

To use this feature, you have to add an action postback URL on the Thirdwatch Dashboard. The action postback URL is something you need to configure on your server. Thirdwatch simply sends the action postback to this URL for your consumption. Every time an action is taken on an order on the Thirdwatch Dashboard, the information is sent to the action postback URL.

To add an action postback URL:

Log into the Dashboard.
Navigate to Settings → Configure.
Add the relevant URL in the Action Postback URL field.

Refer to the short animation below for more information.

Webhook Payload#

Copy{
  "order_id":"orderId",
  "action_type":"approved",
  "action_message":"actionMessage"
}

Parameters#

order_id

Data type string. This is the order_id used in the Thirdwatch Orders API. For example, Axn167SnweX.

action_type

Data type string. The action taken on the Dashboard. Possible values:

approved
on_hold
declined

action_message

Data type string. A user-entered message when the decision was taken.

Address Update API#

To use this feature, you have to add a shipping address postback URL on the Thirdwatch Dashboard. This postback URL is something you need to configure on your server. Every time the shipping address is updated on the Thirdwatch Dashboard, the information is sent to the shipping address postback URL.

To add an address postback URL:

Log into the Dashboard.
Navigate to Settings → Configure.
Add the relevant URL in the Shipping Address Postback URL field.

Refer to the short animation below for more information.

Webhook Payload#

Copy{
  "order_id": "4040",
  "shipping_address": {
    "name": "Gaurav Kumar",
    "address1": "105 Floor, Millennium Towers",
    "address2": "1st Street",
    "zipcode": "560099",
    "city": "Bangalore",
    "region": "Karnataka",
    "country": "India",
    "past_delivery": "nodata",
    "phone": "9876543210",
    "address_type": "Landmark",
    "is_office_address": false,
    "is_home_address": true
  }
}

Update Status#

Once you have processed and shipped the order, you need to capture its final status. This information is consumed by Thirdwatch AI to learn patterns, behavior and helps prevent fraud in the future.

The real-time status of the update of an order can be captured using this API. The status can be updated at an overall order level as well as at an individual item level.

Update Order Status#

The below endpoint updates the status of an order. This endpoint can be called multiple times to record changes in an order's status.

/thirdwatch/order_status

 Request 200 OK
Copycurl -X POST https://api.razorpay.com/v1/thirdwatch/order_status \
-H 'X-THIRDWATCH-API-KEY: <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
      "user_id":"saurav_kumar",
      "session_id":"565ghUY8UI654VGsdmnbfjhs",
      "order_id":"7374734324",
      "order_status":"fulfilled",
      "reason":"other",
      "shipping_cost":"50",
      "tracking_number":"374t873284768746",
      "tracking_method":"http://fedex.com/track?q=abc123",
      "source":"_manualReview",
      "analyst":"asa_fox@afrodogenterprises.com",
      "descriptions":"approved for shipping"
    }'
Copy{
  "status": "Success"
}

Request Parameters#

user_idmandatory

Data type string. The ID of the user who placed the order. This has to be the same as the user_id used in the Thirdwatch Order API. For example, AsXcYnkERrjb.

order_idmandatory

Data type string. This has to be the same as the order_id used in the Thirdwatch Orders API. For example, Axn167SnweX.

order_statusmandatory

Data type string. The status of the order. You can assign values as per your business case. We recommend using the following values:

approved - The order has been approved for shipping.
fulfilled - The order has been successfully delivered to the customer.
cancelled - The order was cancelled by you and was not considered for delivery.
rto - The order was dispatched, but was returned to origin.
returned - The order was successfully delivered, but the customer returned the product.
held - The delivery for this item is put on hold.

reasonoptional

Data type string. The reason for cancellation. For example, Wrong pincode.

session_idoptional

Data type string. This can be alternately passed with User ID provided that the same Session ID was passed in the Orders request.

shipping_costoptional

Data type string. The shipping cost in the currency subunit. For example, if the shipping cost is ₹75, pass 7500.

tracking_numberoptional

Data type string. The tracking number for the order. For example, 374t873284768746.

tracking_methodoptional

Data typestring. URL to track the shipment. For example, http://fedex.com/track?q=abc123.

sourceoptional

Data type string. The source from where the update was received. For example, Updated in delivery bay.

analystoptional

Data type string. The ID of the person in your team who updated the order. For example, saurav.kumar@exampleenterprises.com.

descriptionoptional

Data type string. A user-entered comment when updating the order. For example, Approved for shipping.

Update Item Status#

The below endpoint updates the status of an item. This endpoint can be called multiple times to record changes in an order's status.

/thirdwatch/item_status

 Request 200 OK
Copycurl -X POST https://api.razorpay.com/v1/thirdwatch/item_status \
-H 'X-THIRDWATCH-API-KEY: <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
      "user_id": "saurav_kumar",
      "session_id": "565ghUY8UI654VGsdmnbfjhs",
      "order_id": "7374734324",
      "item_id": "AS34",
      "item_status": "fulfilled",
      "reason": "other",
      "shipping_cost": "50",
      "tracking_number": "374t873284768746",
      "tracking_method": "http://fedex.com/track?q=abc123",
      "source": "manualReview",
      "analyst": "asa_fox@afrodogenterprises.com",
      "description": "approved for shipping"
    }'
Copy{
  "status": "Success"
}

Request Parameters#

user_idmandatory

Data type string. This has to be the same as the user_id used in the Thirdwatch Orders API. For example, AsXcYnkERrjb.

order_idmandatory

Data type string. This has to be the same as the order_id used in the Thirdwatch Orders API. For example, Axn167SnweX.

item_idmandatory

Data type string. This is the unique identifier for the item passed in the order. For example, AS34.

item_statusmandatory

Data type string. Status of the item. You can assign values as per your business case. We recommend using the following values:

approved - The item has been approved for shipping.
fulfilled - The item has been successfully delivered to the customer.
cancelled - The item was cancelled by you and was not considered for delivery.
rto - The item was dispatched but was returned to origin.
returned - The item was successfully delivered, but the customer returned the product.
held - The delivery for this item is put on hold.

reasonoptional

Data type string. The reason for cancellation. For example, Wrong pincode.

session_idoptional

Data type string. This can be alternately passed with User ID provided that the same Session ID was passed in the Orders request.

shipping_costoptional

Data type string. The shipping cost in the currency subunit. For example, if the shipping cost is ₹75, pass 7500.

tracking_numberoptional

Data type string. The tracking number for the order. For example, 374t873284768746.

tracking_methodoptional

Data typestring. URL to track the shipment. For example, http://fedex.com/track?q=abc123.

sourceoptional

Data type string. The source from where the update was received. For example, Updated in shipping bay.

analystoptional

Data type string. The ID of the person in your team who updated the order. For example, saurav.kumar@exampleenterprises.com.

descriptionoptional

Data type string. A user-entered comment when updating the order. For example, Approved for shipping.

Seller User Case#

The Orders API of Thirdwatch also supports the Seller use-case. The Seller entity stores details of the Seller registered on the Merchant website. These details need to be passed with every order request.

Orders API#

/thirdwatch/orders

 Request Example Response
Copycurl -X POST https://api.razorpay.com/v1/thirdwatch/orders \
-H 'X-THIRDWATCH-API-KEY: <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
  "device":{
    "ip":"192.178.0.1",
    "session_id":"5f7dok65iif989fwrmn88er47gk834",
    "user-agent":"Mozilla/5.0 (Linux; <Android Version>; <Build Tag etc.>)AppleWebKit/<WebKit Rev> (KHTML, like Gecko) Chrome/<Chrome Rev> MobileSafari/<WebKit Rev>"
  },
  "user":{
    "id":"AsXcYnkERrjb",
    "created_at":"1578924272676",
    "email":"gaurav.kumar@example.com",
    "first_name":"Gaurav",
    "last_name":"Kumar",
    "contact":"+919876543210",
    "first_purchase":true,
    "email_verification":"verified",
    "contact_verification":"verified"
  },
  "order":{
    "id":"Axn167SnweX",
    "created_at":"1578924272676",
    "amount":"1560000",
    "currency":"INR",
    "prepaid":true,
    "items":[
      {
        "id":"XQF1576BGY",
        "title":"Office Bag",
        "amount":"50000",
        "currency":"INR",
        "brand":"Renegade X",
        "category":"Apparels > Men > Bag",
        "quantity":10,
        "is_onsale":true,
        "sku":"167380XBGEB"
      }
    ],
    "shipping_address":{
      "name":"Gaurav Kumar",
      "phone":"+919876543210",
      "line1":"221B Bakery Street",
      "line2":"14th Main Road, 3rd Cross",
      "city":"Bengaluru",
      "state":"Karnataka",
      "country":"IN",
      "postal_code":"560069",
      "type":"home"
    },
    "promotions":[
      {
        "id":"XPY100",
        "status":"applied",
        "amount":"100",
        "type":"discount",
        "currency":"INR"
      }
    ],
    "payment":{
      "id":"Axf26ns78G",
      "status":"success",
      "gateway":"Razorpay",
      "amount":"15600",
      "currency":"INR",
      "method":"card",
      "bank":"YESB",
      "wallet":"",
      "card":{
        "last4":"6600",
        "type":"credit",
        "issuer":"YESB",
        "international":false,
        "name":"Gaurav Kumar",
        "iin":"456078",
        "expiry_year":"23",
        "expiry_month":"11"
      }
    }
  },
  "seller":{
    "id":"Ax17Ybc",
    "name":"Asa Fox",
    "email":"asa.fox@examplecompany.com",
    "contact":"+919988770099",
    "created_at":"1581402439000",
    "updated_at":"1581402439004",
    "device":{
      "ip":"192.178.0.1",
      "session_id":"5f7dok65iif989fwrmn88er47gk834",
      "user-agent":"Mozilla/5.0 (Linux; <Android Version>; <Build Tag etc.>) AppleWebKit/<WebKit Rev> (KHTML, like Gecko) Chrome/<Chrome Rev>Mobile Safari/<WebKit Rev>"
    }
  }
}'
Copy{
  "success": true,
  "message": "Order details processed successfully."
}

Request Parameters#

device

Details of the device being used to place the order.

Note:
If device details are passed via Front-end, all parameters in this array can be passed as empty strings.

ipmandatory: Data type string. The IP address from where the order is being placed. For example, 192.178.0.1.
session_idmandatory: Data type string. The unique identifier for the session.
user-agentmandatory: Data type string. Details of the browser being used to place the order. For example, Mozilla/5.0.

user

This entity contains information related to the customer making the purchase. This information is important to understand the fraudulent behavior of delinquent customers.

idmandatory

Data type string. Your customer’s account ID according to your system. This field is case-sensitive. For example, AsXcYnkERrjb.

created_atmandatory

Data type string. The Unix timestamp in milliseconds of when the customer account was created in your system. For example, 1578487238129.

emailmandatory

Data type string. The customer's email address. For example, gaurav.kumar@example.com. Note:
If the customer’s email is also their account ID in your system, set both the user_id and email fields to their email address.

first_namemandatory

Data type string. The customer's first name. For example, Gaurav.

last_namemandatory

Data type string. The customer's last name. For example, Kumar.

contactmandatory

Data type string. The customer's phone number. For example, 9123456789.

first_purchasemandatory

Data type boolean. Set to true if the customer is a first-time buyer.

email_verificationmandatory

Data type string. Status of email verification. Possible values:

unverified (default)
pending
verified

contact_verificationmandatory

Data type string. Status of phone number verification. Possible values:

unverified (default)
pending
verified

order

Details of the order being created.

idmandatory

Data type string. A unique identifier for the order created in your system. For example, Axn167SnweX.

created_atmandatory

Data type string. The Unix timestamp in milliseconds of when the order was created in your system. For example, 1578487238129.

amountmandatory

Data type string. The order amount in the currency subunit. For example, if the order amount is ₹15,600 pass 1560000.

currencymandatory

Data type string. The 3-letter ISO currency code for the order amount. For example, INR.

prepaidmandatory

Data type boolean. Pass true if the order is prepaid.

item

This entity contains an array of items, consisting of item details such as amount, currency, brand, category, and quantity.

idmandatory: Data type string. A unique identifier for an item created in your system. Use the same ID that you would use to look up items on your website's database. For example, XQF1576BGY.
titlemandatory: Data type string. The item's name. For example, Awesome bag to impress your friends.
amountmandatory: Data type string. The item amount in the currency subunit. For example, if the order amount is ₹15,600 pass 1560000.
currencymandatory: Data type string. The 3-letter currency code for the item amount. For example, INR.
brandmandatory: Data type string. The brand name of the item. For example, Office bags.
categorymandatory: Data type string. The category the item is listed under in your business. For example, "Office bags", "man > bags".
quantitymandatory: Data type integer. Quantity for the item. For example, 4.
is_onsalemandatory: Data type boolean. Indicates if the item is on sale. Set to true if the item is on sale.
skuoptional: Data type string. The stock-keeping unit ID (SKU) for the item, if available. For example, 167380XBGEB.

shipping_address

Address where the order is to be shipped.

namemandatory

Data type string. Provide the full name associated with the address here. Concatenate first name and last name together if you collect them separately in your system. For example, Gaurav Kumar.

phonemandatory

Data type string. The phone number associated with this address. Provide the phone number as a string starting with the country code. For example, +919123456789.

line1mandatory

Data type string. The first line of the shipping address. For example, 221B Bakery Street.

line2mandatory

Data type string. The second line of the address. For example, 14th Main Road, 3rd Cross.

citymandatory

Data type string. The city or town name. For example, Bengaluru.

statemandatory

Data type string. The state where the address is to be shipped. For example, Karnataka.

countrymandatory

Data type string. The 2-letter ISO country code where the order is to be shipped. For example, IN for India.

postal_codemandatory

Data type string. The postal code to which the order is to be shipped. For example, 560069.

typemandatory

Data type string. The type of address. Possible values:

home
office
other

promotions

An array of promotions applied to the order.

idoptional

Data type string. The unique identifier for the coupon code in your system. For example, ADbb.

statusoptional

Data type string. The status of the addition of promotion to an order. This way you can pass both successful and failed attempts to Thirdwatch when using a promotion. This may be useful in spotting potential abuse. Possible values:

applied
failed

typeoptional

Data type string. Possible values:

discount
cashback
store_credit
voucher

amountoptional

Data type string. The amount or credits the promotion is worth in the currency subunits. For example, if the promotion is worth ₹50 pass 5000.

currencyoptional

Data type string. The 3-letter ISO currency code for the amount. For example, INR.

payment

This entity holds the information of the payment transaction made against the Order.

idmandatory

Data type string. The unique identifier for the payment. This is important to track transactions and to link different parts of the same transaction, such as a refund, together.

statusmandatory

Data type string. The status of the payment. Possible values:

pending
success
failure

gatewaymandatory

Data type string. The gateway used for carrying out transactions. For example, razorpay.

amountmandatory

Data type string. The amount for the payment in the currency subunits. For example, if the payment is worth ₹7,500 pass 750000.

currencymandatory

Data type string. The 3-letter ISO currency code for the payment. For example, INR.

methodmandatory

Data type string. The method used to make the payment. Possible values:

card
wallet
upi
netbanking
cod
fund_transfer

bankoptional

Data type string. Name of bank from which the payment was made. For example, State Bank of India.

walletoptional

Data type string. Name of wallet from which the payment was made. For example, amazonpay.

card

Details of the card used to make the payment.

last4optional

Data type string. Last 4 digits of the card. For example, 0305

typeoptional

Data type string. The type of card used to make the payment. Possible values:

debit
credit
gift
prepaid

issueroptional

Data type string. The name of the bank issuing the card. For example, State Bank of India.

internationaloptional

Data type boolean. Pass true if the card has been issued outside India. Defaults to false.

iinoptional

Data type string. First 6 digits of the card number. For example, 305619.

expiry_monthoptional

Data type string. The expiry month for the card in the MM format. For example, if the card expires in October, pass 10.

expiry_yearoptional

Data type string. The expiry year for the card in the YY format. For example, is the expiry year is 2022, pass 22.

nameoptional

Data type string. The name of the cardholder. For example, Gaurav Kumar.

seller

This entity stores details of the Seller registered on the Merchant website. The Seller details need to be passed with every order.

idoptional

Data type string. The unique identifier for the seller's internal account. For example, Ax17Ybc.

nameoptional

Data type string. The name associated with the seller's account. For example, Asa Fox.

emailoptional

Data type string. The email address associated with the seller's account. For example, asa.fox@examplecompany.com.

contactoptional

Data type string. The contact number associated with the seller's account. For example, +919988770099.

created_atoptional

Data type string. The Unix timestamp in milliseconds when the seller completed the registration process. For example, 1578924272676.

updated_atoptional

Data type string. The Unix timestamp in milliseconds when the seller's profile was last updated. For example, 1578924272676.

device

Details of the device used by the seller to place the order.

ipoptional: Data type string. The IP address used by the seller when placing the order. For example, 192.178.0.1.
session_idoptional: Data type string. The unique identifier for the session.
user-agentoptional: Data type string. Details of the browser used by the seller to place the order. For example, Mozilla/5.0.