Transaction Risk Verification

API Format

Base URL

Singapore：https://sg.apitd.net/verification/persona/transaction/v3
America：https://us.apitd.net/verification/persona/transaction/v3
Germany：https://de.apitd.net/verification/persona/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

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	Required/Optional	Description	Notes
transaction_time	String	required	transaction time	The transaction time in format YYYYMMDDHHMMSS, e.g.20260416134043
transaction_amount	String	required	transaction amount	The amount of the transaction in the currency’s basic unit. If the transaction amount is USD 123.45, the element will contain the value 12345
transaction_currencyexponent	String	required	The transcation currency exponent	If the transaction amount is USD 123.45, then the exponent will contain 2.
transaction_currency	String	required	The currency of the transaction amount	as an ISO-4217 currency code, e.g.840
merchant_name	String	required	The name of the business
merchant_countrycode	String	required	The country code of the merchant associated with the transaction	The ISO-3166 country code, e.g.840 or US
mcc	String	required	The Merchant Category Code associated with the transaction
ip	String	optional	Public IP Address	IPV4 and IPV6 supported
billing_name	String	optional	billing name	Characters <=45
billing_phone_country_id	String	optional	billing phone country_id	e.g.86
billing_phone	String	optional	billing phone
billing_email	String	optional	billing email
billing_address_country_id	String	optional	billing address country_id	The ISO-3166 country code, e.g.840 or US
billing_address_state_id	String	optional	billing address state_id
billing_address_postal_id	String	optional	billing address postal_id
billing_address_city	String	optional	billing address city
billing_address_street1	String	optional	billing address street1	Characters <=50
billing_address_street2	String	optional	billing address street2	Characters <=50
shipping_name	String	optional	shipping name	Characters <=100
shipping_phone_country_id	String	optional	shipping phone country_id	e.g.86
shipping_phone	String	optional	shipping phone
shipping_email	String	optional	shipping email
shipping_address_country_id	String	optional	shipping address country_id	The ISO-3166 country code, e.g.840 or US
shipping_address_state_id	String	optional	shipping address state_id
shipping_address_postal_id	String	optional	shipping address postal_id
shipping_address_city	String	optional	shipping address city
shipping_address_street1	String	optional	shipping address street1	Characters <=50
shipping_address_street2	String	optional	shipping address street2	Characters <=50
user_agent	String	optional	The user-agent string of the consumer device attempting to authorize your product or service	The user-agent must represent the HTTP client of the service consumer with details on the software originating the request
timezone	String	optional	Time-zone of the consumer device	he timezone must be a number of the time-zone offset, in minutes, from the date based on current host system settings to UTC, e.g.100 or -100
screen_width	String	optional	The screen width of the consumer device attempting to authorize with your product or service
screen_height	String	optional	The screen height of the consumer device attempting to authorize with your product or service
language	String	optional	The language of the consumer device. The language must be a string representing the language version as defined in BCP-47
colordepth	String	optional	The device screen color depth value
model	String	optional	Mobile device manufacturer and model	Android: Build.MANUFACTURER + " " + Build.MODEL returns the mobile device manufacturer and model, For example,“samsung SM-G960U1” iOS: utsname machine returns the device model, For example, “iPhone10.4”. Note: Apple as a manufacturer is not included because it is the same for all iOS devices.
major_os_version	String	optional	Major operating system version
minor_os_version	String	optional	Minor operating system version
account_number	String	optional	Unique identifier for the primary account number of the card
card_last4	String	optional	The last four digits of the card number
card_expirydate	String	optional	The expiry year and month of the card in YYMM format
card_bin	String	optional	The first digits of the card number
acquirer_merchant_id	String	optional	The merchant ID that the transaction was processed under, as assigned by the acquirer
acquirer_bin	String	optional	The BIN (Bank Identification Number) of the acquirer
work_phone_country_id	String	optional	work phone country_id	e.g.86
work_phone	String	optional	work phone
extra	String	optional	Expand field, in Json string format	Can be empty

Request Example

{
  "transaction_time": "20260416134043",
  "ip": "23.129.64.214",
  "billing_name": "xxxxxx",
  "billing_phone_country_id": "1",
  "billing_phone": "3143978691",
  "billing_email": "[email protected]",
  "billing_address_country_id": "840",
  "billing_address_state_id": "TX",
  "billing_address_postal_id": "63124",
  "billing_address_city": "Houston",
  "billing_address_street1": "912 Uclan Dr",
  "shipping_name": "xxxxx",
  "shipping_phone_country_id": "1",
  "shipping_phone": "3143978691",
  "shipping_email": "[email protected]",
  "shipping_address_country_id": "840",
  "shipping_address_state_id": "TX",
  "shipping_address_postal_id": "63124",
  "shipping_address_city": "Houston",
  "shipping_address_street1": "912 Uclan Dr",
  "extra": "",
  "transaction_amount": "12500",
  "transaction_currencyexponent": "2",
  "transaction_currency": "840",
  "merchant_name": "Acme Inc",
  "merchant_countrycode": "US",
  "mcc": "5411",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
  "timezone": "600",
  "screen_width": "1512",
  "screen_height": "982",
  "language": "en-GB",
  "colordepth": "30",
  "endcustomerrefId": "45342",
  "model": "iPhone10.4",
  "major_os_version": "12",
  "minor_os_version": "0",
  "account_number": "4111111111111111",
  "card_last4": "1111",
  "card_expirydate": "2311",
  "card_bin": "411111",
  "acquirer_merchant_id": "ACME",
  "acquirer_bin": "444444",
  "work_phone_country_id": "1",
  "work_phone": "3143978691"
}

Response Parameter

Parameter	Type	Description	Notes
code	Integer	API Status Code
message	String	Status Message	specific abnormal reasons will be provided if the API is abnormal
sequence_id	String	Unique ID of Response	A unique ID used to mark each request
risk_score	Integer	risk score, range: 0 - 100
risk_score_reason_code	String	reason code explanation value for the risk score	The meaning can be found in Appendix 1
device_risk_score	Integer	device risk score, range: 0 - 100
ip_risk_score	Integer	ip risk score, range: 0 - 100
ip_carrier	String	ip carrier
ip_connection_type	String	ip Connection type description	cable-dsl corporate cellular dialup
ip_geolocation_city	String	ip geolocation city
ip_geolocation_country_code	String	ip geolocation country_code
ip_geolocation_state	String	ip geolocation state
ip_last_seen_days	Integer	Number of days that have passed since the ip address was last seen
ip_proxy	Boolean	a flag indicating whether the ip is suspected to be a proxy ip
ip_proxy_riskclass	String	an indicator of the riskiness associated to the type of the proxy ip
billing_address_first_seen_days	Integer	Number of days that have passed since the address was first seen
billing_address_last_seen_days	Integer	Number of days that have passed since the address was last seen.
billing_address_shipping_address_relationship	String	The relationship between billing and shipping address	match city_match seen_together seen_with_others no_relationship null
billing_address_to_name	String	The match status between either of the input names and the queried entity	not-found match no-match
billing_address_validity_level	String	The most granular level to which the address could be validated	missing_address invalid valid_to_country valid_to_city valid_to_street valid_to_house_number valid_to_house_number_missing_apt valid
billing_email_disposable	Boolean	true if the email domain is disposable
billing_email_domain_creation_date	String	The date when the email domain was created. Format is YYYY-MM-DD
billing_email_first_seen_days	Integer	Count of days since the email was first observed in Identity Network. If the email has not been observed before, firstSeenDays will be 0
billing_email_last_seen_days	Integer	Number of days that have passed since the email address was last seen
billing_email_risk_score	Integer	email risk score, range: 0 - 100
billing_email_to_name	String	The match status between the input name and the queried entity	not-found match no-match
billing_email_valid	Boolean	true if the email address is valid	true false
billing_email_velocity	Integer	Number of times email has been seen in last 180 days
billing_ip_address_distance	Integer	The distance (in miles) between the IP address and the physical address
billing_phone_carrier	String	The company that provides voice and/or data services for the phone number
billing_phone_to_name	String	The match status between either of the input names and the queried entity	not-found match no-match
billing_phone_type	String	The line type of the phone number	landline：Traditional wired phone line fixed-voip：VOIP-based fixed line phones non-fixed-voip：Skype, for example mobile：Wireless phone line voicemail：Voicemail-only service toll-free：Callee pays for call premium：Caller pays a premium for the call other：Anything that does not match the previous categories
billing_phone_valid	Boolean	true if the phone number is valid	true false
shipping_address_first_seen_days	Integer	Number of days that have passed since the address was first seen
shipping_address_last_seen_days	Integer	Number of days that have passed since the address was last seen
shipping_address_to_name	String	The match status between either of the input names and the queried entity	not-found match no-match
shipping_address_validity_level	String	The most granular level to which the address could be validated	missing_address invalid valid_to_country valid_to_city valid_to_street valid_to_house_number valid_to_house_number_missing_apt valid
shipping_ip_address_distance	Integer	The distance (in miles) between the IP address and the physical address
shipping_phone_carrier	String	The company that provides voice and/or data services for the phone number
shipping_phone_to_name	String	The match status between either of the input names and the queried entity	not-found match no-match
shipping_phone_type	String	The line type of the phone number	landline：Traditional wired phone line fixed-voip：VOIP-based fixed line phones non-fixed-voip：Skype, for example mobile：Wireless phone line voicemail：Voicemail-only service toll-free：Callee pays for call premium：Caller pays a premium for the call other：Anything that does not match the previous categories
shipping_phone_valid	Boolean	true if the phone number is valid	true false
browser	String	The name of the browser used to authorize your product or service
device_email_payment_first_seen_days	Integer	Number of days since the device, email address and the account number were first seen in our network
device_ip_email_first_seen_days	Integer	Number of days since the device, IP and email address were first seen in our network
device_ip_first_seen_days	Integer	Number of days since the device and IP were first seen in our network
device_ip_payment_first_seen_days	Integer	Number of days since the device, IP and the account number associated to the payment method were first seen in our network
device_ip_tz_difference	String	The difference between the browser’s time zone and the IP’s time zone	Null: Invalid inputs 0 – Low Risk 1 - Medium Risk 2+ – High Risk
devicet_ype	String	The device type used to authorize your product or service
platform	String	The device platform used to authorize your product or service
card_holder_name_first_seen_days	Integer	Count of days since the payment card and name was first observed in the network
card_holder_name_velocity	Integer	Count of times the payment card and name have been observed in the network over the past 90 days
merchant_category_ratio	String	A ratio of the purchase amount compared to the median purchase amount seen for other similar merchants in the same category. The higher the ratio means that the purchase amount is further from the median purchase amount observed.
work_phone_carrier	String	The company that provides voice and/or data services for the phone number
work_phone_to_name	String	The match status between either of the input names and the queried entity	not-found match no-match
work_phone_type	String	The line type of the phone number	landline：Traditional wired phone line fixed-voip：VOIP-based fixed line phones non-fixed-voip：Skype, for example mobile：Wireless phone line voicemail：Voicemail-only service toll-free：Callee pays for call premium：Caller pays a premium for the call other：Anything that does not match the previous categories
work_phone_valid	Boolean	true if the phone number is valid	true false

API Status Code

code	含义
200	Success
301	Service not purchased
302	Traffic blocked
303	Traffic insufficient
304	Service expired
305	Daily maximum volume reached
9600	System error
9606	Illegal parameter

Response Example

{
  "code": 200,
  "message": "",
  "sequence_id": "1648777165770866F82AC7F326307055",
  "risk_score": 77,
  "risk_score_reason_code": "JB",
  "device_risk_score": 98,
  "ip_risk_score": 86,
  "ip_last_seen_days": 0,
  "ip_geolocation_country_code": "US",
  "ip_geolocation_city": "Colorado Springs",
  "ip_carrier": "xxxxxxx",
  "ip_geolocation_state": "Colorado",
  "ip_proxy": true,
  "ip_proxy_riskclass": "high",
  "ip_connection_type": "cable-dsl",
  "billing_email_risk_score": 89,
  "billing_email_valid": true,
  "billing_email_velocity": 9,
  "billing_email_disposable": false,
  "billing_email_to_name": "match",
  "billing_email_domain_creation_date": "1995-08-13",
  "billing_email_first_seen_days": 6979,
  "billing_email_last_seen_days": 0,
  "billing_phone_valid": true,
  "billing_phone_type": "premium",
  "billing_phone_carrier": "xxxxxx",
  "billing_phone_to_name": "no-match",
  "billing_ip_address_distance": 954,
  "billing_address_validity_level": "valid",
  "billing_address_to_name": "no-match",
  "billing_address_first_seen_days": 1437,
  "billing_address_last_seen_days": 0,
  "billing_address_shipping_address_relationship": "match",
  "shipping_phone_valid": true,
  "shipping_ip_address_distance": 954,
  "shipping_address_validity_level": "valid",
  "shipping_address_to_name": "no-match",
  "shipping_address_first_seen_days": 1011,
  "shipping_address_last_seen_days": 0,
  "shipping_phone_to_name": "no-match",
  "shipping_phone_type": "premium",
  "shipping_phone_carrier": "xxxxx",
  "devicet_ype": "Mac",
  "browser": "Chrome",
  "platform": "Mac OS X",
  "device_ip_tz_difference": 840,
  "device_ip_first_seen_days": 0,
  "device_ip_payment_first_seen_days": 0,
  "device_ip_email_first_seen_days": 0,
  "device_email_payment_first_seen_days": 0,
  "work_phone_to_name": "no-match",
  "work_phone_valid": true,
  "work_phone_type": "premium",
  "work_phone_carrier": "xxxxx",
  "card_holder_name_first_seen_days": 0,
  "card_holder_name_velocity": 0,
  "merchant_category_ratio": 2.6
}

附录1

Reason code	含义
AA	Consumer Identity is suspicious
AB	Increased Risk associated with Email
AC	Increased Risk associated with Email & IP
AD	Increased Risk associated with Email & Address
AE	Increased Risk associated with Email & Phone
AF	Increased Risk associated with Email & Name
AG	Increased Risk associated with IP
AH	Increased Risk associated with IP & Phone
AI	Increased Risk associated with IP & Address
AJ	Increased Risk associated with IP & Name
AK	Increased Risk associated with Address
AL	Increased Risk associated with Address & Phone
AM	Increased Risk associated with Address & Name
AN	Increased Risk associated with Name
AO	Increased Risk associated with Name & Phone
AP	Increased Risk associated with Phone
AQ	Increased Risk associated with Device & Email
AR	Increased Risk associated with Device & IP
AS	Increased Risk associated with Address & Device
AT	Increased Risk associated with Device & Name
AU	Increased Risk associated with Device & Phone
AV	Increased Risk associated with Email & Payment
AW	Increased Risk associated with IP & Payment
AX	Increased Risk associated with Address & Payment
AY	Increased Risk associated with Name & Payment
AZ	Increased Risk associated with Payment & Phone
JA	New Consumer or not sufficient information
JB	Medium Risk Signals associated with Email
JC	Medium Risk Signals associated with Address
JD	Medium Risk Signals associated with Phone
JE	Medium Risk Signals associated with Name
JF	Medium Risk Signals associated with IP
RA	Consumer Trust Established across all elements
RB	Established Credibility for Email
RC	Established Credibility for Email & IP
RD	Established Credibility for Email & Address
RE	Established Credibility for Email & Phone
RF	Established Credibility for Email & Name
RG	Established Credibility for IP
RH	Established Credibility for IP & Phone
RI	Established Credibility for IP & Address
RJ	Established Credibility for IP & Name
RK	Established Credibility for Address
RL	Established Credibility for Address & Phone
RM	Established Credibility for Address & Name
RN	Established Credibility for Name
RO	Established Credibility for Name & Phone
RP	Established Credibility for Phone
RQ	Established Credibility for Device & Email
RR	Established Credibility for Device & IP
RS	Established Credibility for Address & Device
TY	Established Credibility for Device & Name
RU	Established Credibility for Device & Phone
RV	Established Credibility for Email & Payment
RW	Established Credibility for IP & Payment
RX	Established Credibility for Address & Payment
RY	Established Credibility for Name & Payment
RZ	Established Credibility for Payment & Phone