# verifyOTP

Alipay+ uses the **verifyOTP** API to request that the Mobile Payment Provider (MPP) verifies whether the one-time password (OTP) provided by the user is correct. This API is used in risk control scenarios where the user identity needs to be verified with OTPs. 

**Note**: In the following sections, the MPP is also known as PSP. For example, _pspId_ refers to the ID that identifies an MPP .

# Structure

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

-   [Request header](api_overview#3mLq0)
-   [Response header](api_overview#YdmVS)

> **Note**:
>
> 1.  Set the data type of each parameter (except array) as String. This means that you must use double quotation marks (" ") to enclose the parameter value. Examples:
>
> -   If the data type of a parameter is Integer and its value is 20, set it as "20".
> -   If the data type of a parameter is Boolean and its value is `true`, set it as "true".
>
> 2.  For optional parameters that are not required in your case, you can take one of the following actions:
>
> -   Exclude the parameters from the request body.
> -   Set the parameter values as `null` (without the double quotation marks).
>
> Do NOT leave the optional parameters empty by setting their values as `""`; otherwise, an error might occur.

## Request parameters

#### acquirerId (String, REQUIRED)

The unique ID that is assigned by Alipay+ to identify an Acquiring Service Provider (ACQP).

More information:

- Maximum length: 64 characters

#### pspId (String, REQUIRED)

The unique ID that is assigned by Alipay+ to identify an MPP.

More information:

- Maximum length: 64 characters

#### accessToken (String, REQUIRED)

The token that is used to access the MPP user's resources. 

For the **verifyOTP** API, the access token is used to specify the user.

More information:

- Maximum length: 128 characters

#### verifyRequestId (String, REQUIRED)

The unique ID that is assigned by MPP to identify an OTP.

More information:

- Maximum length: 64 characters

#### otpCode (String, REQUIRED)

The OTP code provided by the user. The MPP uses the OTP code for verification.

More information:

- Maximum length: 32 characters

## Response parameters

#### result (Result, REQUIRED)

The result of the OTP verification. If the value of the _result_._resultCode_ parameter is `SUCCESS`, the OTP is correct. For more information about how to return the OTP verification result, see _How to return the result_.

##### resultCode (String, REQUIRED)

The result code that indicates the detailed processing result.

More information:

- Maximum length: 64 characters

##### resultStatus (String, REQUIRED)

The result status that indicates the processing result. Valid values are:

-   `S`: Successful
-   `F`: Failed
-   `U`: Unknown

##### resultMessage (String)

The result message that describes the result code in detail.

It is recommended that you specify this parameter to provide details about the result.

More information:

- Maximum length: 256 characters

## More information

### How to return the result

According to the business processing result, the MPP needs to return the corresponding result (specified by the result parameter):

-   If the OTP verification succeeds, set the value of _result.resultStatus_ to `S` and the value of _result.resultCode_ to `SUCCESS`.
-   If the OTP verification fails, set the value of _result.resultStatus_ to `F` and the value of _result.resultCode_ accordingly.
-   If the OTP verification result is unknown, set the value of _result.resultStatus_ to `U` and the value of _result.resultCode_ accordingly.

For more information about how to define your result codes, see the _Result codes_ section below.

## Result/Error codes

| Code | Value | Message |
| --- | --- | --- |
| SUCCESS | S | Success |
| ACCESS_DENIED | F | Access is denied. |
| EXPIRED_ACCESS_TOKEN | F | The access token is expired. |
| INVALID_CLIENT | F | The client is invalid. |
| INVALID_SIGNATURE | F | The signature is invalid. |
| INVALID_TOKEN | F | The access token is invalid. |
| KEY_NOT_FOUND | F | The key is not found. |
| MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. |
| METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTPS method. |
| NO_INTERFACE_DEF | F | API is not defined. |
| OTP_VERIFY_TIMES_EXCEED_LIMIT | F | The OTP verification has failed too many times. The user must get a new OTP. |
| OTP_VERIFY_UNMATCHED | F | The OTP code is invalid. |
| PARAM_ILLEGAL | F | Illegal parameters. For example, non-numeric input, invalid date. |
| PROCESS_FAIL | F | A general business failure occurred. Do not retry. |
| USER_NOT_EXIST  | F | The user does not exist. |
| USER_STATUS_ABNORMAL | F | The user status is abnormal. |
| VERIFY_REQUEST_ID_INVALID | F | The value of the verifyRequestId parameter is invalid. |
| REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. |
| UNKNOWN_EXCEPTION | U | An API call failed, which is caused by unknown reasons. |

## Request

### ALIPAY, ALIPAY_HK, DANA, H5, DIRECT

```json
{
  "acquirerId": "1022188000000000000",
  "pspId": "1022172000000000000",
  "accessToken": "281010033AB2F588D14B43238637264FCA5A0000",
  "verifyRequestId": "0b9fc14b15718153091352139110000",
  "otpCode": "660000"
}
```

## Response

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  }
}
```