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

ParameterTypeDescriptionRequired/OptionalNotes
channelStringChannelrequiredassigned by TD
session_idStringSession IDrequiredThe 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_eventStringVerification Eventrequiredenumeration:
order_create
order_payment
event_timeStringThe Actual Time of the EventrequiredISO 8601, format YYYY-MM-DDTHH:mm:ss.sssZ, example: 2021-10-12T14:20:50.521+07:00
account_idStringAccount IDconditionally required: required when account registration/creation is finishednot required when the account doesn't exist
order_idStringOrder IDrequired
terminalTerminalDevice Informationrequired
extExtExtended Fieldconditionally required: required when the extended field is used for policy.extended field registered in the TD system
accountAccountAccount Informationstrongly recommended
orderOrderOrder Informationrequired
paymentPaymentPayment Informationstrongly recommended
payment_resultPaymentResultPayment Resultstrongly recommended
billingBillingBilling Informationstrongly recommended
merchantMerchantMerchant Informationstrongly 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

ParameterTypeDescriptionRequired/OptionalNotes
codeIntegerAPI Status Coderequired
messageStringStatus Messagerequiredspecific abnormal reasons will be provided if the API is abnormal
sequence_idStringUnique ID of ResponserequiredA unique ID used to mark each request
scoreIntegerRisk Scorerequiredrange: 0 - 100
resultStringDecision Resultrequiredenumeration:
decline
review
accept
reasonsArrayDecision Reasonsrequired
idStringDecision Reason IDrequiredeach decision reason has a unique id
reasonStringDecision Reasonrequired

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"
        }
    ]
}