API Reference
中文

Promotion Abuse Prevention Verification API

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

API

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

example: https://sg-efficient.apitd.net/fraud/promo/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:
marketing
marketing_code
marketing_exchange
send_gift
get_coupon
withdraw
invite
sms
browse
activate
lookup
like
comment
favorite
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
terminalTerminalDevice Informationrequired
extExtExtended Fieldconditionally required: required when the extended field is used for policy.extended field registered in the TD system
event_detailObjectEvent Informationrequiredevent 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.

EventEvent Type
Marketingmarketing
MarketingCodemarketing_code
MarketingExchangemarketing_exchange
SendGiftsend_gift
GetCouponget_coupon
Withdrawwithdraw
Inviteinvite
SMSsms
Browsebrowse
Activateactivate
Lookuplookup
Likelike
Commentcomment
Favoritefavorite

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

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

Response Example

{
    "code": 200,
    "message": "",
    "sequence_id": "1648777165770866F82AC7F326307055",
    "score": 90,
    "result": "decline",
    "reasons": [
        {
            "id": "IDRBVBBY",
            "reason": "Suspicious behavioral patterns / frequency"
        }
    ]
}