modifyAuthentication

2022-07-04 05:45

POST /ams/api/v1/customer/modifyAuthentication

Use this API to set, change, and reset a PIN of the user.

Note:
When modifying or setting a PIN, users are required to enter a unique password (PIN), or SMS code (OTP, one-time password) to protect the user's account security according to region regulations and DWS’s risk control requirements. So, before calling the API to change or reset the payment password, you must use this API to initialize the authentication flow, and then use the triggerChallenge API to trigger authentication and complete verification by the verifyAuthentication API.

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
customerId	String	Yes	The unique ID that is used to identify a buyer. This field is composed of 16 digits and begins with 21. More information about this field: Maximum length: 32 characters	"2162878776333"
authenticationRequestId	String	Yes	The unique ID that is assigned by a merchant to identify a password modification 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. Merchant uses the authenticationRequestId field for idempotency control. For password Initialization 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.	"54635453532638728382372"
authenticationMethod	String	Yes	This field indicates the method by which the user's identity is verified. Valid values are: `PASSWORD`: password `OTP`: One Time Password (OTP), like verification code `THIRD_PARTY`: third-party certification	"PASSWORD"
authenticationType	String	Yes	This field indicates the specific type to be verified, that is, what to verify. 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 a high risk.	"PAYMENT"
identityType	String	Yes	This field indicates the type of things that can be used to authenticate users. Valid values are: `CIPHERTEXT`: ciphertext `EMAILNO`: email number `MOBILENO`: mobile phone number `PLAINTEXT`: plain text `CARD_TOKEN`: a permanent token of a card `CARD_BIN`: Bank Identification Number of a card	"CIPHERTEXT"
identityValue	String	No	The identity value that authenticates the user's identity information. When identityType is `CIPHERTEXT`, the new encrypted PIN. When identityType is `MOBILENO`, the mobile phone number.	A new payment password: "m+qPSfvHVzoIXJw3bKckgtHdMXknQ4lt1A9hR8Jg/WIrAUyYA0g5obCdvY/S50wbb2A5fOfWEK+E/8iGbDjOaxpa62UbwKh1VUIqBhVFGesBTOfn/B7lb3+F9HtWU3SaeSodcXWKH0IZJvYgMSDrzit29vsW67NQOX1aAvtWHVwRbP0Rx015lH/L2uTfqBm6pwqR1muGCxy9VnjgTjtpKrDw2Y/abIt5iEYBFA+iZro4v4r+9RC092BLX4mIUZbebI0Q2WblvzGCiMRDLSlZShmnPCzJXTZ674A/zpvh+kjouFL3Lekcgos6l6KUzw9VupyWkSXJyRKU1JTs+zI67A=="
authenticationBizScene	String	Yes	The business type that modifies the value of the authenticated identity. Valid values are: `MODIFY`: change the PIN when forgot. `RESET`: reset the PIN. `SET`: set a PIN, which is not during the registration process. `NEW_SET`: set a new PIN.	"MODIFY"
challengeData	ChallengeData	No	The data returned when challenged after risk consultation. See ChallengeData for details.
publicKeyUniqueId	String	No	The unique ID of the public key, which is used to encrypt the password. It can only be used one time, and it must be regenerated by using the applyPublicKey API before each transmission of the password. More information about this field: Maximum length: 32 characters	"pWBuJqB7MXBf5qEyvDmXtP0bWvt7Uj0B"

Response parameters

Field	Data type	Required	Description	Examples
result	Result	Yes	The request result, which contains information such as status and error codes.	/
authenticationRequestId	String	No	The unique ID that is assigned by a merchant to identify a password modification request. More information about this field: Maximum length: 64 characters	"5678909876567890987656789"
expirySeconds	String	No	The expiration seconds of OTP. More information about this field: Maximum length: 8 characters	"60"
expiryTime	Datetime	No	The expiration time of OTP. The value follows the ISO 8601 standard format. More information about this field: Maximum length: 16 characters	"2019-11-27T12:01:01+08:30"
length	String	No	The length of OTP. More information about this field: Maximum length: 8 characters	"6"
genCount	String	No	The generation times of idempotent. More information about this field: Maximum length: 4 characters	"2"
value	String	No	The value of OTP. More information about this field: length: 6 digits	"123221"
totalErrorTimes	String	No	The number of times an OTP value or payment password was sequentially entered incorrectly. More information about this field: Maximum 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: Maximum length: 4 characters Note: This field is returned when result.resultStatus is `F`.	"3"
locked	String	No	Whether the password is locked. Note: This field is returned when result.resultStatus is F. Valid values are: `TRUE`: locked `FALSE`: not locked	"TRUE"
lastErrorTime	Datetime	No	The last time that an incorrect value was entered. The value follows the ISO 8601 standard format. More information about this field: Maximum length: 16 characters 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.	When need to do OTP verification: { "challengeRenderValue": "+6222***508", "challengeType": "SMS" } When need to do PIN verification { "challengeRenderValue": "", "challengeType": "PAYMENT_PASSWORD" }
authenticationId	String	No	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	"cb3153b48564e5faace8efaea6fd5b06435d6ee976603285e7fe262e17e07717"

Result processing logic

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

Result status	Description
S	The modifyAuthentication request is accepted successfully. The corresponding result.resultCode is `SUCCESS`, and the result.resultMessage is `SUCCESS`.
U	The status of the modifyAuthentication 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 modifyAuthentication 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	/
USER_STATUS_ABNORMAL	F	The user status is abnormal.	Contact the digital wallet to check the user status.
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.
KEYBOARD_SEQUENCE_CHAR	F	The password cannot be continuous keyboard characters.	Check whether the password contains continuous keyboard characters.
PWD_DECRYPT_ERROR	F	The password decryption fails.	Apply for the public key again and restart the password operation process. Or contact Alipay Technical Support for detailed reasons.
PAY_PASSWORD_ALREADY_EXIST	F	The password already exists.	Appears when setting a password, no need to set it.
PWD_NOT_DIGIT	F	The password should only contain digits.	Check whether the password contains digits only .
PAY_PASSWORD_LENGTH_WRONG	F	The password length is wrong.	Check whether the password containis 6 digits only.
PAY_PASSWORD_CONTAINS_ILLEGAL_CONSECUTIVE	F	The password contains illegal consecutive, including all same numbers or characters.	Check whether the password contains illegal consecutive characters.
RISK_REJECT	F	The request is rejected because of the risk control.	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.

Samples

request

The merchant sends a request to Alipay to initialize the authentication flow for resetting PIN.

copy

{
        "authenticationBizScene":"RESET",
   			"authenticationMethod":"PASSWORD",
        "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
        "authenticationType":"PAYMENT",
        "customerId":"216276867889",
        "identityType":"CIPHERTEXT",
        "identityValue": null
}

The merchant sends a request to Alipay to reset the PIN.

copy

 {
        "authenticationBizScene":"RESET",
   			"authenticationMethod":"PASSWORD",
        "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
        "authenticationType":"PAYMENT",
        "customerId":"216276867889",
        "identityType":"CIPHERTEXT",
        "identityValue": "m+qPSfvHVzoIXJw3bKckgtHdMXknQ4lt1A9hR8Jg/WIrAUyYA0g5obCdvY/S50wbb2A5fOfWEK+E/8iGbDjOaxpa62UbwKh1VUIqBhVFGesBTOfn/B7lb3+F9HtWU3SaeSodcXWKH0IZJvYgMSDrzit29vsW67NQOX1aAvtWHVwRbP0Rx015lH/L2uTfqBm6pwqR1muGCxy9VnjgTjtpKrDw2Y/abIt5iEYBFA+iZro4v4r+9RC092BLX4mIUZbebI0Q2WblvzGCiMRDLSlZShmnPCzJXTZ674A/zpvh+kjouFL3Lekcgos6l6KUzw9VupyWkSXJyRKU1JTs+zI67A==",
        "publicKeyUniqueId":"pWBuJqB7MXBf5qEyvDmXtP0bWvt7Uj0B"
}

response

DWS returns the request result of authentication initialization for resetting PIN.

copy

{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "expirySeconds": null,
  "expiryTime": null,
  "length": null,
  "genCount": null,
  "value": null,
  "totalErrorTimes": null,
  "remainTryTimes": null,
  "locked": null,
  "lastErrorTime": null,
  "actionForm": {
    "challengeRenderValue": "+6222***508",
    "challengeType": "[\"sms\"]"
  },
  "authenticationId": "ea3c40047c8d1781167bb00486242e0ebe0d53139f23e356eaa24d09f415bbf0",
  "bizDate": null,
  "success": true,
  "result": {
		"resultCode": "SUCCESS",
		"resultStatus": "S",
		"resultMessage": "success"
	}
}

DWS returns the request result of PIN resetting.

copy

{
    "remainTryTimes":"0",
    "result": {
		"resultCode": "SUCCESS",
		"resultStatus": "S",
		"resultMessage": "success"
	}
}