initAuthentication
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:
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:
In the registration scenario, only | "OTP" |
authenticationType | String | Yes | The concrete type of authentication method that is used to authenticate the user. Valid values are:
In the registration scenario, this field is | "SMS" |
identityType | String | Yes | The type is used to verify the user. Valid values are:
In the registration scenario, this field is | "MOBILENO" |
identityValue | String | Yes | The value that authenticates the user's identity information. When the value of identityType is 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 | 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 | 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.
| "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:
| "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 |
U | The status of the initAuthentication request is unknown. The corresponding result.resultCode is |
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.
{
"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.
{
"actionForm":{
"challengeRenderValue":"+60******6353",
"challengeType":"sms"
},
"authenticationId":"20220105190077000000162140200586657",
"authenticationRequestId":"MDEDUCT001bd856ad81cec1e91a620c270bcba5a4223",
"result":{
"resultCode":"SUCCESS",
"resultMessage":"success.",
"resultStatus":"S"
}
}