API ReferenceIntegrationsKnowledge Base

Thirdwatch APIs

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. Your API key is sent to your registered email id after you activate your account. You can also find this on the Thirdwatch Dashboard, under the SettingsGeneral tab.

Watch this video for more information.

  • Every API request should contain the API Key X-THIRDWATCH-API-KEY in the header.
  • Every API request should include your user_id. If this is not available, you can alternatively provide a session_id value.

Device and User Information🔗

You can collect customer information by creating a device fingerprint.

A fingerprint is a unique hashed string identifier generated by combining the hashed values of device parameters, such as the user agent, plugins installed, webGL rendering information, device OS, and fonts installed. Thirdwatch’s Fingerprint SDK generates this identifier for the user and passes it to Thirdwatch. This helps identify customers better 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. Add this script to the page that is accessed by your customer. For example, if you want to track three different web pages, paste the below script on each webpage, just after the opening tag.

Do not want to pass device details to Thirdwatch using the front-end?
If you do not want to pass device details to Thirdwatch using the front-end, you can instead use the Thirdwatch Orders API.

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>

Script Parameters

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. For a guest user, use the session ID.
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. Our system picks the session id by our reading its value from the cookie name.
data-session-id-valueoptional
Data type string. If you are not passing data-session-cookie-name, pass the session id using this parameter. If no data-session-cookie-name or data-session-id-value values are available, our system generates a session id.

Orders API🔗

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

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 related to the customer and the orders placed during the transaction.

/thirdwatch/orders
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

The details of the device used to place the order.

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

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

The details of the customer placing the order. This information is vital to understand the fraudulent behaviour 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 id. For example, gaurav.kumar@example.com. Note:
If the customer’s email id is also the account id in your system, set both the user_id and email fields to their email id.
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. The status of email verification. Possible values:
  • unverified (default)
  • pending
  • verified
contact_verificationmandatory
Data type string. The status of phone number verification. Possible values:
  • unverified (default)
  • pending
  • verified
order

The details of the order.

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 contains an array of items with 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 will 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 item 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 on your website under which the item is listed. For example, "Office bags", "man > bags".
quantitymandatory
Data type integer. The number or quantity of 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

The address details 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

The promotion details 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. The type of promotion. Possible values:
  • discount
  • cashback
  • store_credit
  • voucher
amountoptional
Data type string. The amount of 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

The payment details for the order.

idmandatory

Data type string. The unique identifier for the payment. This helps 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 payment. 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. The name of the bank used by the customer to make the payment. For example, State Bank of India.

walletoptional

Data type string. The name of the wallet used by the customer to make the payment. For example, amazonpay.

card

The details of the card used to make the payment.

last4optional
Data type string. The last 4 digits of the card used. For example, 0305
typeoptional
Data type string. The type of card used. 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. Default is false.
iinoptional
Data type string. The first 6 digits of the card number. For example, 305619.
expiry_monthoptional
Data type string. The expiry month of the card in MM format. For example, if the card expires in October, pass 10.
expiry_yearoptional
Data type string. The expiry year of the card in 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.

Orders API - Seller Use Case🔗

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

Orders API🔗

/thirdwatch/orders
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

The details of the device used to place the order.

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

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

The details of the customer making the payment. This information is vital to understand the fraudulent behaviour 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 id. For example, gaurav.kumar@example.com. Note:
If the customer’s email id is also the account id in your system, set both the user_id and email fields to their email id.
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. The status of email verification. Possible values:
  • unverified (default)
  • pending
  • verified
contact_verificationmandatory
Data type string. The status of phone number verification. Possible values:
  • unverified (default)
  • pending
  • verified
order

The details of the order that is 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 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 will 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 under which the item is listed in your business. For example, "Office bags", "man > bags".
quantitymandatory
Data type integer. The number or quantity of 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. 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

The details of the payment made for the order.

idmandatory

Data type string. The unique identifier for the payment. It helps 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 to make the payment. 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. The name of the bank using which the payment was made. For example, State Bank of India.

walletoptional

Data type string. The name of the wallet using which the payment was made. For example, amazonpay.

card

The 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. 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 is issued outside India. Default is false.
iinoptional
Data type string. The first 6 digits of the card number. For example, 305619.
expiry_monthoptional
Data type string. The expiry month of the card in MM format. For example, if the card expires in October, pass 10.
expiry_yearoptional
Data type string. The expiry year of the card in 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

The details of the seller registered on the merchant's 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 id 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

The details of the device used by the seller to place the order.

ipoptional
Data type string. The IP address used by the seller while 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. The details of the browser used by the seller to place the order. For example, Mozilla/5.0.

Retrieve Analyzed Results🔗

After you create an order, Thirdwatch analyses 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:

Configure Score Postback URL🔗

To check the response, you can configure your Score Postback URL on the Thirdwatch Dashboard.

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

To add a Score Postback URL:

  1. Log on to the Thirdwatch Dashboard.
  2. Navigate to SettingsConfigure.
  3. Add the score postback URL in the Score Postback URL field.

Watch this video for more information.

Webhook Payload

Copy{ "order_id": "Axn167SnweX", "user_id": "AsXcYnkERrjb", "order_timestamp": 1601388449000, "flag": "red", "reasons": [ { "flag": "red", "name": "_shipAddressHasDigits", "display_name": "Shipping Address looks incomplete", "value": "kachakali, P.O-Chandani Danga, P.S-Chopra kachakali", "is_display": true }, { "flag": "red", "name": "_highRtoZipcode", "display_name": "High RTO across Zipcode", "value": "733207", "is_display": true }, { "flag": "red", "name": "_numOfSameItemsForEmailInOneDay", "display_name": "Multiple same items from same email id in 24 hours", "value": "gaurav.kumar@example.com No of items 2", "is_display": true }, { "flag": "red", "name": "_numOfSameItemsForMobileInOneDay", "display_name": "Multiple same items from same mobile no in 24 hours", "value": "9999999999 No of items 2", "is_display": true } ], "score": 0, "api_key": "f1f1d1b111", "tags": [ "Address", "HighRtoZipcode", "MultipleSameItemsInADay" ] }

Payload Parameters

order_id

Data type string. This should be 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 same as the user_id used in the Thirdwatch Orders API. For example, AsXcYnkERrjb.

order_timestamp

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

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 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 Thirwdwatch Dashboard.

name
Data type string. The rule name set on the Thirdwatch Dashboard.
display_name
Data type string. The display rule name set on the Thirdwatch Dashboard.
flag
Data type string. The nature of flagging by the rule.
value
Data type string. The level of impact your custom rule has on the flagged order.
api_key

Data type string. This is your API key.

tags

Data type array. Possible values of tags:
Address, Email, ZipCode, Phone, MultipleSameItemsInADay, MultipleSameItemInAnOrder, HighValueCOD, DynamicRule, NetworkFlag, HighRto, HighRtoZipcode, Merchant Notes, multipleSameItemInAWeek, CustomerName, AddressTest

Score API🔗

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

/thirdwatch/score?order_id=:id
Copycurl -X GET https://api.razorpay.com/v1/thirdwatch/score?order_id=Axn167SnweX \ -H 'X-THIRDWATCH-API-KEY: <API_KEY>' \
Copy{ "flag": "red", "reasons": [ { "flag": "red", "name": "_shipAddressHasDigits", "display_name": "Shipping Address looks incomplete", "value": "test Nirvana Country, Sector 50" }, { "flag": "red", "name": "_testAddressOrder", "display_name": "Address contains Test", "value": "test Nirvana Country, Sector 50" }, { "flag": "red", "name": "_shipAddressStateIsSameAsZipCodeState", "display_name": "Shipping address state different from zipcode state", "value": "delhi" }, { "flag": "red", "name": "_numOfSameItemsForEmailInOneDay", "display_name": "Multiple same item from same email id in 24 hours", "value": "gaurav.kumar@example.com No of items 4" }, { "flag": "red", "name": "_numOfSameItemsForMobileInOneDay", "display_name": "Multiple same item from same mobile no in 24 hours", "value": "9999999999 No of items 4" } ], "user_id": "AsXcYnkERrjb", "order_timestamp": "2020-10-05T11:39:32Z", "order_id": "Axn167SnweX", "tags": [ "Address", "AddressTest", "ZipCode", "MultipleSameItemsInADay" ], "score": 0 }

Response Parameters

order_id

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

user_id

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

order_timestamp

Data type string. For example, "2020-10-05T11:39:32Z"

score

Data type integer. The probability score calculated by Thirdwatch 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 the 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 rule name set on the Thirdwatch Dashboard.
display_name
Data type string. The rule display name set on the Thirdwatch Dashboard.
flag
Data type string. The nature of flagging by the rule.
value
Data type string. The impact of the rule on the flagged order.
tags

Data type array. Possible values of tags:
Address, Email, ZipCode, Phone, MultipleSameItemsInADay, MultipleSameItemInAnOrder, HighValueCOD, DynamicRule, NetworkFlag, HighRto, HighRtoZipcode, Merchant Notes, multipleSameItemInAWeek, CustomerName, AddressTest

Synchronize Actions and Order Status with Thirdwatch🔗

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

There are three APIs for this.

  • Action API
    Using this API, you can pass the 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 can 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
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 should be same as the order_id used in the Thirdwatch Orders API. For example, Axn167SnweX.
action_typemandatory
Data type string. The action taken on the Thirdwactch 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 should be configured on your server. Thirdwatch 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:

  1. Log on to the Thirdwatch Dashboard.
  2. Navigate to SettingsConfigure.
  3. Add the relevant URL in the Action Postback URL field.

Watch this video 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 Thirdwatch 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 should be configured 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:

  1. Log on to the Thirdwatch Dashboard.
  2. Navigate to SettingsConfigure.
  3. Add the relevant URL in the Shipping Address Postback URL field.

Watch this video 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🔗

After you have processed and shipped the order, you need to capture its final status. This information is consumed by Thirdwatch AI to learn patterns and behaviour and 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
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 should be same as the user_id used in the Thirdwatch Order API. For example, AsXcYnkERrjb.
order_idmandatory
Data type string. This should be 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 is approved for shipping.
  • fulfilled - The order is 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 order 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 the user id provided 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 type string. The 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 while 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
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 should be same as the user_id used in the Thirdwatch Orders API. For example, AsXcYnkERrjb.
order_idmandatory
Data type string. This should be 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. The status of the item. You can assign values as per your business case. We recommend using the following values:
  • approved - The item is approved for shipping.
  • fulfilled - The item is 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 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 type string. The 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.
×