The Verification API is used for real-time access to our risk verification results.
In order to effectively prevent fraud and avoid potential financial losses in your promotional campaigns, it is recommended that you send risk verification requests before granting promotional discounts or immediately after granting them but before the discounts are redeemed. This can help protect the security of your campaign funds and ensure that only legitimate users can avail the discounts.
API Format
Base URL
- China：https://cn-efficient.apitd.net/fraud/promo/v3
- America：https://us-efficient.apitd.net/fraud/promo/v3
- Singapore：https://sg-efficient.apitd.net/fraud/promo/v3
- Germany：https://de-efficient.apitd.net/fraud/promo/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-efficient.apitd.net/fraud/promo/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: marketing marketing_code marketing_exchange send_gift get_coupon withdraw invite sms browse activate lookup like comment favorite |
| 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 |
| 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 |
| event_detail | Object | Event Information | required | event data object corresponding to the decision_event. special note: event_detail allows the Account data object to be passed in if necessary |
The mapping relationship between the event_detail event data and the decision_event is as follows:
Our API design restricts each request to only include data related to a single business event. This means that you cannot simultaneously pass multiple requests with different types of business event data, such as marketing and withdraw. Adhering to this rule will help improve system performance and reliability, ensuring that each business event is processed correctly.
Request Example
Let's take the example of a marketing event.
{
"channel": "test",
"session_id": "abc0123456789",
"decision_event": "marketing",
"event_time": "2021-10-12T14:20:50.521+07:00",
"account_id": "123456789",
"terminal": {
"black_box": "aGPH1658920283672ropYaFxT7",
"ip": "210.20.10.33"
},
"ext": {
"ext_book_id": "LFOUHOFHOHFNOUH",
"ext_book_num": 10
},
"event_detail": {
"marketing": {
"marketing_id": "X08938",
"open_id": "o6_bmjrPTlm6_2sgVt7hMZOPfL2M",
"open_id_type": "wechat",
"begin_time": 1596358039000,
"expire_time": 1616358039000
},
"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]"
}
}
}
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 |
| 9203 | No corresponding strategy configuration |
Response Example
{
"code": 200,
"message": "",
"sequence_id": "1648777165770866F82AC7F326307055",
"score": 90,
"result": "decline",
"reasons": [
{
"id": "IDRBVBBY",
"reason": "Suspicious behavioral patterns / frequency"
}
]
}