API Reference
中文

Verification API (Required)

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

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