verifyAuthentication

2022-07-04 05:45

POST /ams/api/v1/security/verifyAuthentication

Use this API to verify authentication. When the merchant performs verification initialization and triggers a challenge, call this API to verify the challenge.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

If the data type of a field is Integer and its value is 20, set it as "20".
If the data type of a field is Boolean and its value is true, set it as "true".

Request parameters

Field	Data type	Required	Description	Examples
authenticationRequestId	String	Yes	After the verification initialization, DWS returns authenticationId. The value of authenticationRequestId must be the same during the whole authentication process. More information about this field: length: 128 characters	"54635453532638728382372"
authenticationMethod	String	No	The authentication method. This field indicates the method by which the user's identity is verified. Valid values are: `PASSWORD`: password, verify PIN `OTP`: One Time Password (OTP), verify OTP `THIRD_PARTY`: third-party certification More information about this field: length: 16 characters	"OTP"
authenticationType	String	No	The concrete type of authentication method that is used to authenticate the user. Valid values are: `PAYMENT`: payment password `LOGIN`: login password `EMAIL`: email, one type of sending OTP `SMS`: SMS, one type of sending OTP `THREEDS`: 3ds v2. In October 2016, EMVCo published the specification for 3-D Secure 2.0; it is designed to be less intrusive than the first version of the specification, allowing more contextual data to be sent to the customer's bank (including mailing addresses and transaction history) to verify and assess the risk of the transaction. The customer would only be required to pass an authentication challenge if their transaction is determined to be of high risk. More information about this field: length: 16 characters	"SMS"
authenticationId	String	Yes	The authentication ID throughout the process. Returned when the verification is initialized. More information about this field: length: 64 characters	"20220105190077000000162140200586657"
challengeData	ChallengeData	No	The data returned when challenged after risk consultation. See ChallengeData for details.	{ "challengeType":"PAYMENT_PASSWORD", "passwordValue":"y+ySfvHVzoIXJw3bKckgtHdMXknQ4lt1A9hR8Jg/WIrAUyYA0g5obCdvY/S50wbb2A5fOfWEK+E/8iGbDjOaxpa62UbwKh1VUIqBhVFGesBTOfn/B7lb3+F9HtWU3SaeSodcXWKH0IZJvYgMSDrzit29vsW67NQOX1aAvtWHVwRbP0Rx015lH/L2uTfqBm6pwqR1muGCxy9VnjgTjtpKrDw2Y/abIt5iEYBFA+iZro4v4r+9RC092BLX4mIUZbebI0Q2WblvzGCiMRDLSlZShmnPCzJXTZ674A/zpvh+kjouFL3Lekcgos6l6KUzw9VupyWkSXJyRKU1JTs+zI67A==" }
env	Env	No	The environment information, and data collection for transaction risk. See Env for details.	{ "appVersion": "6.84.2", "clientIp": "175.*..***", "deviceModel": "TECNO LD7", "deviceTokenId": "wiQ5Hlwx3QLMkRS3R3OMtOAnznRWKJ6lFPgs7GDgihiuimC9fQEAAA==", "language": "en-PH", "operateEntrance": "DWS", "osType": "Android", "osVersion": "10", "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c", "terminalType": "APP", "umidTokenId": "DYQAEhpLPO4XcQN9vXk/RHl6C7oLX+41" }

Response parameters

Field	Data type	Required	Description	Examples
result	Result	Yes	The result contains information such as status and error codes.	{ "resultCode":"SUCCESS", "resultMessage":"success.", "resultStatus":"S" }
pass	String	No	Whether this verification is passed. Valid values are: `TRUE`: pass `FALSE`: fail	"TRUE"
authenticationRequestId	String	No	The unique ID that is assigned by a merchant to identify an authentication process. More information about this field: length: 128 characters	"5678909876567890987656789"
totalErrorTimes	String	No	The number of times an OTP value or payment password was sequentially entered incorrectly. More information about this field: length: 4 characters Note: This field is returned when result.resultStatus is `F`.	"3"
remainTryTimes	String	No	The number of remaining tries for verification. More information about this field: length: 4 characters Note: This field is returned when result.resultStatus is `F`.	"3"
lastErrorTime	Datetime	No	The last time that an incorrect value was entered. The value follows the ISO 8601 standard format. Note: This field is returned when result.resultStatus is `F`.	"2019-11-27T12:01:01+08:30"
actionForm	Map<String, Object>	No	The next action to do when the processing result is not the final status, as a reference for the next action. According to challengeType, you can determine the factor to be verified in the next step.

Result processing logic

In the response, the result.resultStatus field indicates the result of the verifyAuthentication request. The following table describes each result status:

Result status	Description
S	The verifyAuthentication request is accepted successfully. The corresponding result.resultCode is `SUCCESS`, and result.resultMessage is `SUCCESS`. If the value of the pass field is `TRUE`, this verification is successful. If the value of the pass field is `FALSE`, this verification is failed. actionForm: Further verification, returned when this verification is successful.
U	The status of the verifyAuthentication request is unknown. The corresponding result.resultCode is `UNKNOWN_EXCEPTION`, and result.resultMessage is `An API call failed, which is caused by unknown reasons.` For details, see the Common error codes section.
F	The verifyAuthentication request failed. The corresponding result.resultCode and result.resultMessage may vary based on different situations. For details, see the following Error codes section.

Error codes

Result code	Result status	Result message	Further action
SUCCESS	S	Success	N/A
REPEAT_REQ_INCONSISTENT	F	Repeated requests are inconsistent.	Ensure the fields in the requests are the same.
PARAM_ILLEGAL	F	Illegal parameters exist. For example, a non-numeric input, or an invalid date.	Check and verify whether the request fields, including the header fields and body fields, are correct and valid. For details on the fields of each API, see the specific API Structure section.
PROCESS_FAIL	F	A general business failure occurred. Don't retry.	Human intervention is usually needed. It is recommended that you contact the technical support team to troubleshoot the issue.
UNKNOWN_EXCEPTION	U	An API call is failed, which is caused by unknown reasons.	Call the interface again to resolve the issue. If the issue persists, contact Alipay Technical Support.
VERIFICATION_ORDER_NOT_EXIST	F	The verification order does not exist.	Check whether authenticationRequestId is the same as authenticationId returned by DWS.
SECURITY_VERIFY_FAILURE	F	Wrong verify value, try again.	Let the user try again.
VERIFY_TIMES_EXCEED_LIMIT	F	Wait a while, please try again later	Please wait a while and try again later.
INVALID_API	F	API is invalid (or not active).	Check whether the API name, HTTP method, or request format is correct when sending the request.
INVALID_CLIENT	F	Invalid client.	Check whether the client ID is correct, or contact Alipay Technical Support for detailed reasons.
INVALID_SIGNATURE	F	Signature is invalid.	Check whether the private key used to sign a request matches the public key of Alipay Developer Center.
REQUEST_TRAFFIC_EXCEED_LIMIT	U	Request traffic exceeds the limit.	Call the interface again to resolve the issue. If the issue persists, contact Alipay Technical Support.
ACCESS_DENIED	F	Access denied.	Contact Alipay Technical Support for detailed reasons.
SEND_TIMES_EXCEED_LIMIT	F	The send times exceed the limit.	Contact Alipay technical support to know the specific limitation.
METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method.	Ensure the HTTP method is POST.
SECURITY_VERIFY_FAILURE	F	Security verification failed.	Let the user try again.

Samples

Request

Wallet sends a request to verify the PIN.

copy

{
  "authenticationMethod": "PASSWORD",
  "authenticationType": "PAYMENT",
  "authenticationId": "20220105190077000000162140200586657",
  "challengeData":{
    "challengeType":"PAYMENT_PASSWORD",
    "passwordValue":"y+ySfvHVzoIXJw3bKckgtHdMXknQ4lt1A9hR8Jg/WIrAUyYA0g5obCdvY/S50wbb2A5fOfWEK+E/8iGbDjOaxpa62UbwKh1VUIqBhVFGesBTOfn/B7lb3+F9HtWU3SaeSodcXWKH0IZJvYgMSDrzit29vsW67NQOX1aAvtWHVwRbP0Rx015lH/L2uTfqBm6pwqR1muGCxy9VnjgTjtpKrDw2Y/abIt5iEYBFA+iZro4v4r+9RC092BLX4mIUZbebI0Q2WblvzGCiMRDLSlZShmnPCzJXTZ674A/zpvh+kjouFL3Lekcgos6l6KUzw9VupyWkSXJyRKU1JTs+zI67A=="
  },
  "env": {
        "osVersion": "8.1.0",
        "tokenId": "giaGTonn30X9AJPc0MN9lpjK-SZXq6PifXy3Gs4ufmI4BC87awEAAAAA",
        "clientIp": "123.136.111.19",
        "clientUmid": "sdjoi02082",
        "osType": "ios 8929",
        "language": "en_US",
        "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType": "APP"
    }

}

Wallet sends a request to verify OTP.

copy

{
  "authenticationMethod": "OTP",
  "authenticationType": "SMS",
  "authenticationId": "20220105190077000000162140200586657",
  "challengeData":{
        "challengeType":"SMS_OTP",
        "otpValue":"666666"
  },
  "env": {
        "osVersion": "8.1.0",
        "tokenId": "giaGTonn30X9AJPc0MN9lpjK-SZXq6PifXy3Gs4ufmI4BC87awEAAAAA",
        "clientIp": "123.136.111.19",
        "clientUmid": "sdjoi02082",
        "osType": "ios 8929",
        "language": "en_US",
        "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType": "APP"
    }

}

Response

Wallet returns the result of successful verification.

copy

{
  "authenticationRequestId": "c2c25606-9f1e-4697-853d-da2517bf67be",
  "pass": "true",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Wallet returns the result of successful verification but requires further verification.

copy

{
  "authenticationRequestId": "c2c25606-9f1e-4697-853d-da2517bf67be",
  "actionForm": {
    "challengeRenderValue": "",
    "challengeType": "PAYMENT_PASSWORD"
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Wallet returns the result of a failed verification.

copy

{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "false",
  "remainTryTimes": "1",
  "result": {
    "resultCode": "SECURITY_VERIFY_FAILURE",
    "resultMessage": "wrong value, can input again",
    "resultStatus": "F"
  }
}