Fraud Management API

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

China：https://cn-efficient.apitd.net/fraud/transaction/v3
America：https://us-efficient.apitd.net/fraud/transaction/v3
Singapore：https://sg-efficient.apitd.net/fraud/transaction/v3
Germany：https://de-efficient.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://us-efficient.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_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

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": "IDZPQJEG",
            "reason": "Suspicious purchasing patterns"
        }
    ]
}