The Verification API is used for you to obtain real-time risk verification results.
To effectively prevent fraud and minimize financial losses, it is recommended that you send a request for risk verification before initiating the funds authorization process through the payment gateway. Alternatively, you can also send a risk verification request immediately after receiving the authorization response from the payment gateway but before capturing the funds. This ensures that a thorough risk assessment is conducted before any financial transactions take place.
API Format
Base URL
- China:https://cn.apitd.net/fraud/transaction/v3
- America:https://us.apitd.net/fraud/transaction/v3
- Singapore:https://sg.apitd.net/fraud/transaction/v3
- Germany:https://de.apitd.net/fraud/transaction/v3
API
URL | Request Methods | Content-Type | Output Format | Character Set |
---|---|---|---|---|
api-base-url?partner_code=xxx&partner_key=xxx | POST | application/json | JSON | UTF-8 |
example: https://sg.apitd.net/fraud/transaction/v3?partner_code=test_code&partner_key=test_key
Authentication
Parameter | Type | Description | Required/Optional | Notes |
---|---|---|---|---|
partner_code | String | Partner Code | required | assigned by TD |
partner_key | String | Partner Key | required | assigned by TD |
Request
Parameter | Type | Description | Required/Optional | Notes |
---|---|---|---|---|
channel | String | Channel | required | assigned by TD |
session_id | String | Session ID | required | The session ID is a unique identifier assigned by the website server to a specific user during the visit, which is usually stored in the form of a cookie, form parameter, or URL |
decision_event | String | Verification Event | required | enumeration: order_payment |
event_time | String | The Actual Time of the Event | required | ISO 8601, format YYYY-MM-DDTHH:mm:ss.sssZ, example: 2021-10-12T14:20:50.521+07:00 |
account_id | String | Account ID | conditionally required: required when account registration/creation is finished | not required when the account doesn't exist |
order_id | String | Order ID | required | |
terminal | Terminal | Device Information | required | |
ext | Ext | Extended Field | conditionally required: required when the extended field is used for policy. | extended field registered in the TD system |
account | Account | Account Information | strongly recommended | |
order | Order | Order Information | required | |
payment | Payment | Payment Information | strongly recommended | |
payment_result | PaymentResult | Payment Result | strongly recommended | |
billing | Billing | Billing Information | strongly recommended | |
merchant | Merchant | Merchant Information | strongly recommended |
Request Example
{
"channel": "test",
"session_id": "abc0123456789",
"decision_event": "order_payment",
"event_time": "2023-10-12T14:20:50.521+07:00",
"account_id": "123456789",
"order_id": "ID293846237467",
"terminal": {
"black_box": "aGPH1658920283672ropYaFxT7",
"ip": "210.20.10.33"
},
"ext": {
"ext_book_id": "LFOUHOFHOHFNOUH",
"ext_book_num": 10
},
"account": {
"account_id": "123456789",
"register_time": "2021-10-12T14:20:50.521+07:00",
"login_time": "2021-10-12T14:25:50.521+07:00",
"phone": {
"country_code": 1,
"phone_number": "6165793816"
},
"email": "[email protected]"
},
"order": {
"order_id": "NX348566DIHD",
"order_create_time": "2021-10-12T14:25:50.521+07:00",
"merchandise_list": [
{
"merchandise_id": "NFH837824432",
"category_1": "3c",
"category_2": "phone",
"category_3": "android",
"name": "huawei phone",
"count": 1,
"unit_price": {
"currency": "USD",
"amount_local": 1000,
"amount_usd": 1000,
"amount_cny": 6800
}
}
],
"amount": {
"currency": "USD",
"amount_local": 1000,
"amount_usd": 1000,
"amount_cny": 6800
},
"shipping": {
"address": {
"country": "FR",
"region": "Grand Est",
"city": "Strasbourg City",
"district": "Ketali Lorem",
"detail": "3213 Building,lorem Street",
"zip_code": "310000"
},
"phone": {
"country_code": 1,
"phone_number": "18700001112"
},
"email": "[email protected]",
"consignee": {
"first_name": "Pierre",
"middle_name": "",
"last_name": "Laurent",
"nickname": "Snochy"
},
"method": "logistics"
}
},
"payment": {
"payment_id": "NHF8736274",
"method": "card",
"channel": "paypal",
"amount": {
"currency": "USD",
"amount_local": 68,
"amount_usd": 10,
"amount_cny": 68
},
"card": {
"card_bin": "622207",
"last_four_digits": "1234",
"card_number_length": 16,
"holder_name": {
"first_name": "Pierre",
"middle_name": "",
"last_name": "Laurent",
"nickname": "Snochy"
},
"debit_or_credit": "credit",
"issuer_region": "CN",
"expiration_date": "1998-01-01"
},
"is_coupon_used": true,
"coupons": [
{
"coupon_id": "NOHF08938",
"coupon_name": "Limited Time Discount Coupon",
"coupon_count": 1,
"begin_time": 1596358039000,
"expire_time": 1616358039000,
"coupon_type": "discount",
"coupon_rate": 0.85,
"coupon_threshold": "10",
"cash_back_amount": {
"currency": "USD",
"amount_local": 6.8,
"amount_usd": 1,
"amount_cny": 6.8
}
}
]
},
"payment_result": {
"is_payment_success": true,
"payment_message": "success",
"is_3ds_used": false,
"response_by_3ds": {
"eci_value": "02",
"version": "2.2.0",
"authentication_type": "01",
"trans_status": "Y"
},
"response_by_avs": "",
"response_by_cvc": ""
},
"billing": {
"address": {
"country": "FR",
"region": "Grand Est",
"city": "Strasbourg City",
"district": "Ketali Lorem",
"detail": "3213 Building,lorem Street",
"zip_code": "310000"
},
"phone": {
"country_code": 1,
"phone_number": "18700001112"
},
"email": "[email protected]",
"recipient": {
"first_name": "Pierre",
"middle_name": "",
"last_name": "Laurent",
"nickname": "Snochy"
}
},
"merchant": {
"merchant_id": "NFK00937",
"shop_name": "Hello World",
"shop_phone": {
"country_code": 1,
"phone_number": "18700001112"
},
"shop_email": "[email protected]",
"shop_address": {
"country": "FR",
"region": "Grand Est",
"city": "Strasbourg City",
"district": "Ketali Lorem",
"detail": "3213 Building,lorem Street",
"zip_code": "310000"
},
"shop_url": "https://td/shop/0012",
"register_time": "2021-10-12T14:20:50.521+07:00",
"login_time": "2021-10-12T14:22:50.521+07:00",
"merchant_type": "entity",
"merchant_level": "A",
"company": "XXX",
"primary_category": "XXXX",
"product_count": 1,
"history_order_count": 1,
"history_order_amount": {
"currency": "USD",
"amount_local": 68,
"amount_usd": 10,
"amount_cny": 68
}
}
}
Response Parameter
Parameter | Type | Description | Required/Optional | Notes |
---|---|---|---|---|
code | Integer | API Status Code | required | |
message | String | Status Message | required | specific abnormal reasons will be provided if the API is abnormal |
sequence_id | String | Unique ID of Response | required | A unique ID used to mark each request |
score | Integer | Risk Score | required | range: 0 - 100 |
result | String | Decision Result | required | enumeration: decline review accept |
reasons | Array | Decision Reasons | required | |
id | String | Decision Reason ID | required | each decision reason has a unique id |
reason | String | Decision Reason | required |
API Status Code
code | Description |
---|---|
200 | Success |
301 | Service not purchased |
302 | Traffic blocked |
303 | Traffic insufficient |
304 | Service expired |
305 | Daily maximum volume reached |
9001 | {Parameter} empty |
9002 | {Parameter} check error |
9003 | {Parameter} length or size exceeds 1024 |
9004 | Either black_box or ip exists |
9200 | System error |
9201 | Unknown error |
9202 | Illegal Content-Type |
Response Example
{
"code": 200,
"message": "",
"sequence_id": "1648777165770866F82AC7F326307055",
"score": 90,
"result": "decline",
"reasons": [
{
"id": "IDZPQJEG",
"reason": "Suspicious purchasing patterns"
}
]
}