3DS

Used to verify user identity when the user swipes the card.
You need to provide a callback address and a secret for receiving 3DS notifications.

Set up your 3DS receiver

Request Method: Post

Request Headers

FiledRemark
signatureAll you need to do is take the 3DS's body and apply the SHA-1 hash function with your secret as the hash key. You then compare the resulting HMAC to the one contained in the signature header. If the HMACs are identical, then the data corresponds to what we sent. If they are different, this indicates that the data has been intercepted and altered in some way.
content-typeapplication/json;charset=utf-8

IP address allowlisting

  • Sandbox environment
    • 13.237.90.47
    • 13.210.78.87
    • 54.253.161.136
  • Live environment
    • 52.63.172.6
    • 52.63.244.60
    • 52.65.227.86
    • 52.65.201.21
    • 13.54.136.30
    • 3.104.12.185
    • 3.24.5.91
    • 3.105.126.70

Constant Definition

3DS Event

EventDescription
VERIFICATION_CHOOSEAuthentication Method Selection
OTP_SENDSend a verification code
OOB_SENDSend App message
OOB_VALIDATEValidate the App message

Verification Method

MethodDescription
SMSSMS verification
EMAILEmail verification
OOBAPP message validation

OOB Result

ResultDescription
PENDINGCardholder fails to confirm the transaction request
CONFIRMEDThe cardholder confirms the transaction request
REJECTEDThe cardholder declines the transaction request

Verification Step

Step 1 : Select the authentication method you support

You receive an event for VERIFICATION_CHOOSE, to which you need to return the available authentication methods and languages. The 3DS page will display the available methods to the end-users.
Note that available languages are English(en_US), Simplified Chinese(zh_CN) and Traditional Chinese(zh_TW).

Step 2 : Send verification information to the cardholder

According to the authentication method selected by the end-user, the authentication information will be pushed to you.
If the end-user selects SMS/EMAIL, you will receive Event for OTP_SEND, you need to send the authentication code to the user in the corresponding way, and at the same time return the user's cell phone number/email address, the 3DS page will display this cell phone number/email address to the end-user;
If the end-user selects OOB, you will receive Event for OOB_SEND message, you need to push this message to the end-user for confirmation.

Step 3 : Check the confirmation result of the cardholder

If the user selects OOB validation, we will send a message with Event as OOB_VALIDATE to query the user for the confirmation result.
Note that this step is only available when OOB validation is selected.

Example request and description

Event: VERIFICATION_CHOOSE

  • Request:
{
  "request_id":"1668184762436685824",
  "uid":"1668184762436685823",
  "card_id":"ETLPzgGfSzg.pq",
  "event":"VERIFICATION_CHOOSE",
  "options":["EMAIL","SMS","OOB"]  
}
FieldDescription
request_idRequest ID
uidUser ID
card_idCard ID
event3DS Event
options3DS Verification Methods
  • Response:
{
  "code": 0,
  "msg": "",
  "data":{
    "request_id":"1668184762436685824",
    "event":"VERIFICATION_CHOOSE",
    "options":["EMAIL"],
    "locale":"en_US"
  }
}
FieldDescriptionRemark
codeResponse Code0 Succss,400 Failure
msgError Message
dataResponse Data
data.request_idRequest ID
data.event3DS Event
data.options3DS Verification MethodsOne or more can be selected from request.options
data.locale3ds Page LanguageOptions: en_US, zh_CN, zh_TW

Event: OTP_SEND

  • Request:
{
  "request_id":"1668184762436685824",
  "uid":"1668184762436685823",
  "card_id":"ETLPzgGfSzg.pq",
  "event":"OTP_SEND",
  "option":"EMAIL", 
  "otp":"679023",
  "remark":{
    "merchant_name":"apple.com",
    "amount":"10.00",
    "currency":"AUD"
  }
}
FieldDescription
request_idRequest ID
uidUser ID
card_idCard ID
event3DS Event
option3DS Verification Method,Options: SMS, EMAIL
otpOTP Code
remarkCard Purchase Information,may be empty
remark.merchant_nameMerchant Name
remark.amountAmount
remark.currencyCurrency
  • Response:
{
  "code": 0,
  "data":{
    "request_id":"1668184762436685824",
    "event":"OTP_SEND",
    "email":"abc@gamil.com" 
    "mobile":"+61490789322"  
  }
}
FieldDescriptionRemark
codeResponse Code0 Succss,400 Failure
msgError Message
dataResponse Data
data.request_idRequest ID
data.event3DS Event
data.emailCardholder EmailIf request.option is email, return this field
data.mobileCardholder MobileIf request.option is sms, return this field

Event: OOB_SEND

  • Request:
{
  "request_id":"1668184762436685824",
  "uid":"1668184762436685823",
  "card_id":"ETLPzgGfSzg.pq",
  "event":"OOB_SEND ",
  "option":"OOB", 
  "remark":{
    "merchant_name":"apple.com",
    "amount":"10.00",
    "currency":"AUD"
  }
}
FieldDescription
request_idRequest ID
uidUser ID
card_idCard ID
event3DS Event
option3DS Verification Method,Options: OOB
remarkCard Purchase Information,may be empty
remark.merchant_nameMerchant Name
remark.amountAmount
remark.currencyCurrency
  • Response:
{
  "code": 0,
  "data":{
    "request_id":"1668184762436685824",
    "event":"OOB_SEND"
  }
}
FieldDescriptionRemark
codeResponse Code0 Succss,400 Failure
msgError Message
dataResponse Data
data.request_idRequest ID
data.event3DS Event

Event: OOB_VALIDATE

  • Request:
{
  "request_id":"1668184762436685824",
  "uid":"1668184762436685823",
  "card_id":"ETLPzgGfSzg.pq",
  "event":"OOB_VALIDATE ",
  "option":"OOB" 
}
FieldDescription
request_idRequest Id in requests where Event is OOB_SEND
uidUser ID
card_idCard ID
event3DS Event
option3DS Verification Method,Options: OOB
  • Response:
{
  "code": 0,
  "data":{
    "request_id":"1668184762436685824",
    "event":"OOB_VALIDATE",
    "result":"PENDING" 
  }
}
FieldDescriptionRemark
codeResponse Code0 Succss,400 Failure
msgError Message
dataResponse Data
data.request_idRequest ID
data.event3DS Event
data.resultOOB Confirmation of results