API Reference
中文

Verification API (Required)

The Verification API is used for real-time access to our risk verification results.

To effectively prevent fraud and avoid product or financial losses, it is recommended that you send requests for risk verification at the following business checkpoints. By verifying at these critical points, you can ensure maximum protection for your products and funds.

  • During order creation: This helps to effectively prevent fraudulent activities such as inventory hoarding.
  • During order payment: It is advisable to send a risk verification request before performing the fund authorization on the payment gateway, or immediately after receiving the authorization response from the payment gateway but before actually capturing the funds. This ensures effective risk verification before any transactions take place.

API Format

Base URL

API

URLRequest MethodsContent-TypeOutput FormatCharacter Set
api-base-url?partner_code=xxx&partner_key=xxxPOSTapplication/jsonJSONUTF-8

example: https://sg.apitd.net/fraud/transaction/v3?partner_code=test_code&partner_key=test_key

Authentication
ParameterTypeDescriptionRequired/OptionalNotes
partner_codeStringPartner Coderequiredassigned by TD
partner_keyStringPartner Keyrequiredassigned 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_create
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

codeDescription
200Success
301Service not purchased
302Traffic blocked
303Traffic insufficient
304Service expired
305Daily maximum volume reached
9001{Parameter} empty
9002{Parameter} check error
9003{Parameter} length or size exceeds 1024
9004Either black_box or ip exists
9200System error
9201Unknown error
9202Illegal Content-Type
9203No corresponding strategy configuration

Response Example

{
    "code": 200,
    "message": "",
    "sequence_id": "1648777165770866F82AC7F326307055",
    "score": 90,
    "result": "decline",
    "reasons": [
        {
            "id": "IDZPQJEG",
            "reason": "Suspicious purchasing patterns"
        }
    ]
}