initAuthentication

2022-07-04 05:45

POST /ams/api/v1/customers/initAuthentication

Use this API to initiate a customer authentication event in order to authenticate the user identity. This is the first step in the entire registration process.

Note:
Before calling this API, make sure that the user has a valid mobile phone number for OTP authentication or has already set Payment Password or Login Password for password authentication.

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	The unique ID that is assigned by a merchant to identify an initialization registration request. DWS uses this field for idempotence control. More information about this field: Maximum length: 64 characters Note: This field is an API idempotency field. The merchant uses the authenticationRequestId field for idempotency control. For initialization registration requests that are initiated with the same value of authenticationRequestId and reach a final status (S or F), the same result is to be returned for the request. For details about API idempotency, see the Idempotency chapter.	"MDEDUCT001bd856ad81cec1e91a620c270bcba5a4223"
authenticationMethod	String	Yes	The authentication method. This field indicates the method by which the user's identity is verified. Valid values are: `PASSWORD`: password `OTP`: One Time Password (OTP), such as verification code `THIRD_PARTY`: third-party certification In the registration scenario, only `OTP` is legal for this field.	"OTP"
authenticationType	String	Yes	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. In the registration scenario, this field is `SMS`.	"SMS"
identityType	String	Yes	The type is used to verify the user. Valid values are: `CIPHERTEXT`: ciphertext `EMAILNO`: email `MOBILENO`: mobile number `PLAINTEXT`: plain text `CARD_TOKEN`: a permanent token of card `CARD_BIN`: Bank Identification Number of a card In the registration scenario, this field is `MOBILENO`.	"MOBILENO"
identityValue	String	Yes	The value that authenticates the user's identity information. When the value of identityType is `PASSWORD`, it corresponds to the new encrypted password, and when the value of identityType is `OTP`, enter the value of OTP. In the registration scenario, the value of this field is the user's phone number. The number is expressed as an E.164 number. The format of this field is {countryCode}-{area code with leading 0 removed}{number}".	+14154567899 is a US mobile number with country code as 1, area code as 415, and the local number as 4567899. So, this field should be filled "1-4154567899" (020)44555666 is a UK mobile number, transformed into E.164 is +442044555666, where 44 is the country code, 20 is the area code So this field should be filled "44-2044555666"
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" }
authenticationRequestId	String	Yes	The unique ID that is assigned by a merchant to identify a password modification request. The value of this field is the same as the authenticationRequestId field. Maximum length: 64 characters	"MDEDUCT001bd856ad81cec1e91a620c270bcba5a4223"
actionForm	Map<String, Object>	No	Further action, when the processing result is not in the final state, a reference for what the next action needs to do is provided. According to challengeType, you can determine the factor to be verified in the next step.	When need to do OTP verification: { "challengeRenderValue": "+6222***508", "challengeType": "sms" } When need to do PIN verification { "challengeRenderValue": "", "challengeType": "PAYMENT_PASSWORD" }
authenticationId	String	Yes	The authentication ID throughout the process. The value of this field is used as the value of challengeId when calling the triggerChallenge API. More information about this field: length: 64 characters	"20220105190077000000162140200586657"

Result processing logic

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

Resultstatus	Description
S	The initAuthentication request is accepted successfully. The corresponding result.resultCode is `SUCCESS`, and result.resultMessage is `SUCCESS`.
U	The status of the initAuthentication 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 initAuthentication request is 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	/
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.
INVALID_PHONE_NUMBER	F	Invalid phone number	Check and verify whether the user's phone number has the correct format and is valid.
TIMES_EXCEED_LIMIT	F	Too many requests in a short time, please try again later	Too many requests in a short time, wait for a while to try again.
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.

Samples

Request

The merchant sends a request to initiate a registered customer request.

copy

{
	"authenticationRequestId": "MDEDUCT001bd856ad81cec1e91a620c270bcba5a4223",
	"authenticationMethod": "OTP",
	"authenticationType": "SMS",
	"identityType": "MOBILENO",
	"identityValue": "60-6543216353",
  "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

DWS returns the request result.

copy

{
  "actionForm":{
    "challengeRenderValue":"+60******6353",
    "challengeType":"sms"
  },
  "authenticationId":"20220105190077000000162140200586657",
  "authenticationRequestId":"MDEDUCT001bd856ad81cec1e91a620c270bcba5a4223",
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}