triggerChallenge

2022-07-04 05:45

POST /ams/api/v1/security/triggerChallenge

Use this API to trigger a challenge. With this API call, a merchant can trigger an SMS challenge or a PIN challenge.

This is a step to advance the authentication process after the authentication is initialized. If the authentication method is OTP, an OTP is sent to the user. If the authentication method is PASSWORD, the key-related information is sent to the merchant.

Note:
When the merchant receives the challenge returned by DWS after the verification initialization, the merchant needs to trigger the challenge, and then perform the challenge verification according to the triggered content.
When scene is TOPUP, obtain the ChallengeActionForm field in the topUpApply API or the queryTopUP API before calling this 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
triggerRequestId	String	No	The unique ID that is assigned by a merchant to identify a trigger challenge 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 triggerRequestId field for idempotency control.	"fba0b644-2f9b-4600-b761-faaed5329fc8"
challengeId	String	Yes	After the verification initialization, DWS will return authenticationId. The value of challengeId must be the same as authenticationId returned by the first call to the initAuthentication or modifyAuthentication API. More information about this field: length: 64 characters	"20220105190077000000162140200586657"
scene	BusinessSceneCode	No	Verification method.	"TOPUP"

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"

}

challengeRenderData

ChallengeRenderData

Yes

Challenge rendering information. This field indicates specific challenge information. See ChallengeRenderData for details.

{

"canRetryChallenge": false,

"challengeRenderValue": "+60******2735",

"challengeRenderValueType": "mobile",

"isChallengeFinish": false

}

Result processing logic

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

Result status	Description
S	The triggerChallenge request is accepted successfully. The corresponding result.resultCode is `SUCCESS`, and result.resultMessage is `success`.
U	The status of the triggerChallenge 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 triggerChallenge request failed. The corresponding result.resultCode and result.resultMessage may vary based on different situations. For details, see the following Error codes section.

More information

When calling this interface, pay attention to the following items:

The result returned indicates the acceptance of the registration request.

If resultStatus is S, the trigger challenge request is successful.
If resultStatus is F, the trigger challenge request failed, and you can check resultCode and resultMessage for details.
If resultStatus is U, the system is busy and you can try again.

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 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 challengeId is the same as authenticationId that is returned by DWS.
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 not resolved, contact Alipay Technical Support.
ACCESS_DENIED	F	Access denied.	Contact Alipay Technical Support for detailed reasons.
SEND_TIMES_EXCEED_LIMIT	F	The authentication content sending 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.
AML_REJECT	F	AML_REJECT	Prompt the user that the request is rejected for security reasons.
AML_REVIEW	F	AML_REVIEW	Prompt the user that the request needs to be reviewed because of the high risk.
AMOUNT_EXCEED_LIMIT	F	AMOUNT_EXCEED_LIMIT	Consult Alipay Technical Support about the upper limit.
CHANNEL_ACCOUNT_FROZEN	F	CHANNEL_ACCOUNT_FROZEN	Contact Alipay Technical Support to know the specific reasons.
CHANNEL_OTP_RESPONSE_TIMEOUT	F	Channel OTP response received too late.	Call the interface again to resolve the issue. If the issue persists, contact Alipay Technical Support.
CHANNEL_TOKEN_EXPIRED	F	Access Token expired.	Re-request the access token from the channel.
CONTACT_ISSUER	F	Refer to the card issuer.	Prompt the user to contact the issuer.
COUNT_EXCEED_LIMIT	F	COUNT_EXCEED_LIMIT	Too many requests in a short time. Try again later.
CURRENCY_NOT_SUPPORT	F	The currency is not supported.	Ensure that the currency code is correct and supported.
DUPLICATE_TRANSACTION	F	Duplicate Transaction.	Wait until the previous transaction completes.
EXPIRED_CARD	F	Expired card	Renew the validity period of the card or replace it with a new one.
INVALID_ACCOUNT_NUMBER	F	Invalid account number (no such number).	Check whether the accountNo is correct or contact Alipay Technical Support to know the specific reasons.
INVALID_CHANNEL_MID	F	Partner is not active/create.	Check whether the partner is correct or contact Alipay Technical Support to know the specific reasons.
INVALID_CVV	F	INVALID_CVV	Check whether the cvv is correct and retry again.
OTP_EXCEED_LIMIT	F	The token has been blocked for requesting OTP for certain time intervals.	Too many requests in a short time. Try again later.
OTP_EXPIRED	F	OTP has expired.	Call the interface again to get a new OTP.
OTP_VERIFY_TIMES_EXCEED_LIMIT	F	Verify code failed too many times, the user must get a new code.	Too many requests in a short time. Try again later.
OTP_VERIFY_UNMATCHED	F	Verify code invalid.	Check whether the OTP is correct.
PARAM_ILLEGAL	F	Illegal parameters. For example, non-numeric input, or 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.
PAYMENT_IN_PROCESS	U	Payment is in process.	Do not retry. Human intervention is usually needed. It is recommended that you contact Alipay Technical Support to troubleshoot the issue.
PROCESS_FAIL	F	General business failure. Do not retry.	Prompt the user that the request is rejected because of security reasons.
REQUEST_NOT_FOUND	F	Request not found.	Prompt the user to go through the user information verification.
RISK_BAD_BUYER	F	RISK_BAD_BUYER	Check whether the user information is correct and retry again.
RISK_CHALLENGE	F	RISK_CHALLENGE	Prompt the user that the request is rejected because of the fraud risk.
RISK_CHALLENGE_FAIL	F	RISK_CHALLENGE_FAIL	Prompt the user that the request is rejected because of the risk control.
RISK_FRAUD_RISK	F	RISK_FRAUD_RISK	Contact Alipay Technical Support to know the specific reasons.
RISK_REJECT	F	Reject by risk control.	Top up the account or choose other payment methods.
SYSTEM_MAINTENANCE	F	System maintenance.	Contact Alipay Technical Support to know the specific reasons.
USER_BALANCE_NOT_ENOUGH	F	User balance is not enough for this transfer.	Contact Alipay Technical Support to know the specific reasons.
USER_NOT_EXIST	F	The user does not exist.	Check whether the user information is correct and retry again.
USER_STATUS_ABNORMAL	F	The user status is abnormal.	Contact Alipay Technical Support to know the specific reasons.
VERIFICATION_FAIL	F	The verification failed.	N/A

Samples

Request

The merchant sends a request to trigger a challenge.

copy

{
	"scene": "TOPUP",
	"authenticationId": "2021111819054023100150000210816",
	"triggerRequestId": "trigger_1024343767436",
}

Response

DWS returns the request result.

copy

{
  "challengeRenderData": {
    "canRetryChallenge": false,
    "challengeRenderValue": "+60******2735",
    "challengeRenderValueType": "mobile",
    "isChallengeFinish": false
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}