# consultPayment

`POST /aps/api/v1/payments/consultPayment`

The **consultPayment** API is used by the Acquiring Service Provider (ACQP) to retrieve available payment methods from Alipay+. Currently, this API is used in the Cashier Payment and Auto Debit scenarios.

When a consumer places an order and gets redirected to the cashier page, the merchant must display the available payment methods to the consumer. The ACQP sends a request to Alipay+ on behalf of the merchant to consult the available payment methods. After receiving the response, the ACQP returns the payment method list to the merchant, who then displays the available payment methods on the cashier page.

## 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.md#3mLq0)
-   [Response header](api_overview.md#YdmVS)

**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

#### paymentAmount (Amount, REQUIRED)

The amount that the ACQP requests to receive from Alipay+. The currency of the amount must be specified to the one that the ACQP uses to create the payment order.

**Note**: If the payment amount cannot be provided, set the value of the _paymentAmount.value_ parameter to `0` and specify a value for the _paymentAmount.currency_ parameter.

##### currency (String, REQUIRED)

The currency code of the amount. The value of this parameter must be an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, for example, "EUR" for Euros.

More information:

- Maximum length: 3 characters

##### value (Integer, REQUIRED)

The value of the amount as a natural number. By default, the value of this parameter is in the smallest currency unit. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1, set the value of this parameter to 1.

Due to the currency practices in Indonesia, when the currency is IDR, round the amount with banker's rounding and fix the last two digits of the value of this parameter as `00`.

More information:

- Value range: 0 - unlimited

#### userRegion (String)

This parameter is used to sort the payment method list in descending order based on the relevance between the MPP and the user region on the Alipay+ checkout page. The value of this parameter is a 2-letter country/region code according to [ISO 3166 Country Codes](https://www.iso.org/obp/ui/#search). 

For example, you might receive `ALIPAY_CN` and `KAKAOPAY` as supported MPPs in the result. However, you find out that the user is from South Korea based on the user's IP address or selection. In this case, `KaKaoPay` is placed higher on the list even though both MPPs support the transaction.

**Note**: Required if the ACQP wants to sort the payment method list on the Alipay+ checkout page based on the user region.

More information:

- Maximum length: 2 characters

#### paymentFactor (PaymentFactor, REQUIRED)

Factors that impact payment-related items such as service fee, interchange fee (also known as interpartner fee), and regulatory reporting. This parameter is used to identify the payment scenario.

**Note:**

-   In the Auto Debit scenario, the following child parameters must be set to the specific values as shown below:

-   _isAgreementPayment:_ set the value to `true`

-   In the Cashier Payment scenario, the following child parameters must be set to the specific values as shown below:

-   _isInStorePayment:_ set the value to `false`
-   _isCashierPayment_: set the value to `true`

##### isInStorePayment (Boolean)

Specifies whether the payment scenario is in-store payment. If the value of this parameter is specified as `true`, the payment scenario is in-store payment; otherwise, the payment scenario is online payment.

##### isCashierPayment (Boolean)

Specifies whether a cashier page is presented to the user during the payment. If the value of this parameter is specified as `true`, a cashier page is presented to the user during the payment; otherwise, no cashier page is presented to the user during the payment.

##### inStorePaymentScenario (String)

The in-store payment scenario. Valid values are:

-   `PaymentCode`: indicates the scenario where a user presents a payment code to pay.
-   `OrderCode`: indicates the scenario where a user scans an order code to pay.
-   `EntryCode`: indicates the scenario where a user scans an entry code to pay.

##### isAgreementPayment (Boolean)

Specifies whether the payment scenario is Auto Debit. If the value of this parameter is specified as `true`, the payment scenario is Auto Debit; otherwise, the payment scenario is not Auto Debit.

#### settlementStrategy (SettlementStrategy, REQUIRED)

The settlement strategy that is applied to the payment order, for example, the currency that the ACQP wants to be settled against.

##### settlementCurrency (String)

The currency that the ACQP wants to be settled against. The value of this parameter is an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, for example, "EUR" for Euros.

More information:

- Maximum length: 3 characters

#### merchant (Merchant, REQUIRED)

The merchant information, including the merchant ID, merchant name, merchant category code, and so on.

##### referenceMerchantId (String, REQUIRED)

The unique ID that is assigned by the ACQP to identify a merchant.

More information:

- Maximum length: 32 characters

##### merchantMCC (String)

The merchant category code (MCC) that represents the categorization of the merchant's business type. See [Alipay+ MCC Standards](https://docs.alipayplus.com/alipayplus/alipayplus/mcc-standards/overview.md) for details.

More information:

- Maximum length: 4 characters

##### merchantName (String)

The legal name of the merchant.

More information:

- Maximum length: 256 characters

##### merchantAddress (Address)

In the Cashier Payment and Auto Debit scenarios, specify the region where the merchant is registered. In the User-presented Mode and Merchant-presented Mode Payment scenarios, specify the region where the payment transaction occurs.

###### region (String, REQUIRED)

The region where the address is located. The value of this parameter must be a 2-character country/region code that follows the [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) standard.

More information:

- Maximum length: 2 characters

###### state (String)

The state, country, or province where the address is located.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 8 characters

###### city (String)

The city, district, suburb, town, or village where the address is located.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 32 characters

###### address1 (String)

The address line 1, which contains the street name, PO box, or company name. 

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 256 characters

###### address2 (String)

The address line 2, which contains the apartment, suite, unit, or building name.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 256 characters

###### zipCode (String)

The zip or postal code.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 32 characters

##### merchantDisplayName (String)

The display name of the merchant.

**Note**: It is recommended that you specify this parameter if your display name is different from your legal name. The default value of this parameter is the value of the _merchantName_ parameter.

More information:

- Maximum length: 64 characters

##### merchantRegisterDate (Datetime)

The time when the merchant registered its business at the local regulatory agency.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

##### store (Store)

The information about the store of the merchant.

###### referenceStoreId (String, REQUIRED)

The unique ID that is assigned by the merchant to identify a store.

More information:

- Maximum length: 32 characters

###### storeName (String, REQUIRED)

The legal name of the store.

More information:

- Maximum length: 256 characters

###### storeMCC (String, REQUIRED)

The merchant category code (MCC) that represents the categorization of the store's business type. See [Alipay+ MCC Standards](https://docs.alipayplus.com/alipayplus/alipayplus/mcc-standards/overview.md) for details.

More information:

- Maximum length: 4 characters

###### storeDisplayName (String)

The display name of the store.

**Note**: It is recommended that you specify this parameter if the display name of the store is different from its legal name.

More information:

- Maximum length: 64 characters

###### storeTerminalId (String)

The unique ID that is assigned by the merchant to identify a store terminal.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 64 characters

###### storeAddress (Address)

The address where the store is located.

###### region (String, REQUIRED)

The region where the address is located. The value of this parameter must be a 2-character country/region code that follows the [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) standard.

More information:

- Maximum length: 2 characters

###### state (String)

The state, country, or province where the address is located.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 8 characters

###### city (String)

The city, district, suburb, town, or village where the address is located.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 32 characters

###### address1 (String)

The address line 1, which contains the street name, PO box, or company name. 

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 256 characters

###### address2 (String)

The address line 2, which contains the apartment, suite, unit, or building name.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 256 characters

###### zipCode (String)

The zip or postal code.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 32 characters

#### referenceUserId (String)

The unique ID of the user that is assigned by the merchant.

More information:

- Maximum length: 64 characters

#### env (Env, REQUIRED)

The environment information about the device that is used by the user to place orders.

**Note**: The following child parameters must be specified as follows:

-   _terminalType_
-   _osType_ if the value of _env.terminalType_ is `APP` or `WAP`

##### terminalType (String)

The type of terminal that is used to initiate the payment. 

Valid values are:

-   `WEB`: indicates that a PC browser is used.
-   `WAP`: indicates that a mobile browser is used.
-   `APP`: indicates that a mobile app is used.
-   `MINI_APP`: indicates that a mini program is used.

##### osType (String)

The mobile operating system type. Valid values are:

-   `IOS`: indicates the iOS system
-   `ANDROID`: indicates the Android system

##### deviceTokenId (String)

The token ID of the client device.

**Note**: Specify this parameter if you can obtain the information from the user. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 64 characters

##### clientIp (String)

The IP address of the client device.

**Note**: Specify this parameter if you can obtain the information from the user. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 32 characters

##### cookieId (String)

The cookie ID of the user.

**Note**: Specify this parameter if you can obtain the information from the user. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 64 characters

##### userAgent (String)

The user-agent information.

**Note**: Specify this parameter if you can obtain the information from the user. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 1024 characters

##### storeTerminalId (String)

The ID of the terminal device that is used in the store to process the payment.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 64 characters

##### storeTerminalRequestTime (Datetime)

The time when the request is sent by the terminal device that is used in the store.

**Note**: The value of this parameter must be accurate to milliseconds. If you do not have the terminal request time, specify the time when your gateway received the API request.

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

## Response parameters

#### result (Result, REQUIRED)

The result of the business processing, including the result status, result code, and the result message. For more information about how to handle the result of the **consultPayment** API, see _Result processing logic_.

##### 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.

More information:

- Maximum length: 256 characters

#### paymentOptions (Array<PaymentOption>)

The list of payment options.

**Note**: Returned by Alipay+ if the value of the _result.resultStatus_ parameter is `S`, which means that the consultation succeeds. In this case, apart from the required child parameters, the following optional child parameter is also returned: 

-   _brandName_
-   _logo_

More information:

- Maximum size: 1 element

##### paymentMethodType (String, REQUIRED)

The type of payment method that is included in the payment option. The value is fixed as `CONNECT_WALLET`, which indicates Alipay+ wallets.

More information:

- Maximum length: 32 characters

##### paymentMethodCategory (String, REQUIRED)

The category of the payment method. Valid values are:

`WALLET`: indicates that the payment method is provided by a digital wallet.

##### enabled (Boolean, REQUIRED)

Specifies whether the payment option is available.

##### disableReason (String)

The reason why the payment option is unavailable.

More information:

- Maximum length: 64 characters

##### logo (Logo)

The logo of the payment method.

###### logoName (String, REQUIRED)

The name of the logo.

More information:

- Maximum length: 128 characters

###### logoUrl (URL)

The URL of the logo.

More information:

- Maximum length: 2048 characters

##### brandName (String)

The Alipay+ brand name.

More information:

- Maximum length: 128 characters

##### paymentOptionDetail (PaymentOptionDetail)

The detailed information about the payment option.

###### paymentOptionDetailType (String, REQUIRED)

The type of payment option details. Valid values are:

`CONNECT_WALLET`: indicates that the details are about Alipay+ wallets

###### connectWallet (WalletPaymentOptionDetail)

The details of the wallets that are supported by Alipay+.

**Note**: Required if the value of the _paymentOptionDetailType_ parameter is `CONNECT_WALLET`.

###### supportWallets (Array<Wallet>)

The list of MPPs that are supported by Alipay+.

###### walletName (String, REQUIRED)

The name of the MPP. For its valid values, see [MPP Capabilities](../mpp_list/mpp_capabilities).

More information:

- Maximum length: 64 characters

###### walletBrandName (String)

The brand name of the MPP that is displayed to the customer.

More information:

- Maximum length: 128 characters

###### walletLogo (Logo)

The logo of the MPP.

###### logoName (REQUIRED)

The name of the logo.

More information:

- Maximum length: 128 characters

###### logoUrl (URL)

The URL of the logo.

More information:

- Maximum length: 2048 characters

###### walletRegion

The country or region of the MPP. The value of this parameter must be a 2-character country/region code that follows the [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) standard.

More information:

- Maximum length: 2 characters

###### walletFeature (WalletFeature)

The features that are supported by the MPP.

###### supportCodeScan (Boolean)

Specifies whether the MPP app supports code scanning.

###### supportCashierRedirection (Boolean)

Specifies whether the MPP supports redirection to a Web page for the user to make the payment.

## More information 

**Request conditionality**

The following parameters must be specified to the same values as those of the parameters specified in the **pay** API request: _paymentAmount.currency_, _settlementStrategy,_ and _env_.

**Result process logic**

| **result.resultStatus** | **result.resultCode ** | **Payment status ** | **Actions** |
| --- | --- | --- | --- |
| `S` | `SUCCESS` | The consultation initiation succeeds. The _paymentOptions_ parameter that contains the Alipay+ payment method information is returned in the response. | Render the merchant's cashier page. |
| `F` | Multiple possible values exist, such as `ACCESS_DENIED` and `KEY_NOT_FOUND`. | Consultation fails. | Take actions according to the result code (specified on the _result.resultCode_ parameter). For more information, see the Result code section. |
| `U` | Multiple possible values exist, such as `UNKNOWN_EXCEPTION` and `REQUEST_TRAFFIC_EXCEED_LIMIT`. | Consultation is in processing. | Retry the same request. Ensure that the parameters are the same as the previous ones. |
| No result received | No result received | Unknown. | Retry the same request. Ensure that the value specified on the _paymentRequestId_ parameter is the same as the one specified in the previous request. |

### Sample

### Request

The Acquiring Partner sends a request to Alipay+.

{
  "userRegion": "PH",
  "paymentAmount": {
    "currency": "JPY",
    "value": "0"
  },
  "paymentFactor": {
    "isAgreementPayment": "true"
  },
  "settlementStrategy": {
    "settlementCurrency": "USD"
  },
  "merchant": {
    "referenceMerchantId": "M00000000001"
  },
  "env": {
    "terminalType": "APP",
    "osType": "IOS"
  }
}

### Response

-   Response of a successful consultation, where the value of _result.resultStatus_ is `S`.

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "paymentOptions": \[{
    "paymentMethodType": "CONNECT\_WALLET",
    "paymentMethodCategory": "WALLET",
    "enabled": "true",
    "brandName": "Alipay+™ Partner",
    "logo": {
      "logoName": "AlipayPlus",
      "logoUrl": "https://www.alipayplus.com/logo/20022222xxx.png"
    },
    "paymentOptionDetail": {
      "paymentOptionDetailType": "CONNECT\_WALLET",
      "connectWallet": {
        "supportWallets": \[
          {
            "walletName": "GCASH",
            "walletBrandName": "Gcash",
            "walletLogo": {
              "logoName":"Gcash",
              "logoUrl":"https://www.alipayplus.com/logo/gcash.png"
            },
            "walletRegion": "PH",
            "walletFeature": {
              "supportCodeScan": "true",
              "supportCashierRedirection": "true"
            }
          }
        \]
      }
    }
  }\]
}

-   Response of a failed consultation, where the value of _result.resultStatus_ is `F`, and _resultCode_ and _resultMessage_ indicate the detailed reason for the failure.

{
    "result": {
        "resultCode": "NO\_PAY\_OPTIONS",
        "resultStatus": "F",
        "resultMessage": "A general business failure occurred. Don't retry."
    }
}

-   Response of a consultation with an unknown result, where the value of _result.resultStatus_ is `U`. 

{
    "result": {
        "resultCode": "UNKNOWN\_EXCEPTION",
        "resultStatus": "U",
        "resultMessage": "System Error occurs"
    }
}

## Result/Error codes

| Code | Value | Message | Further action |
| --- | --- | --- | --- |
| SUCCESS | S | SUCCESS. | Render the merchant's cashier page. |
| ACCESS_DENIED | F | Access is denied. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. |
| INVALID_CLIENT | F | The client is invalid. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. |
| INVALID_SIGNATURE | F | The signature is invalid. | Check whether the public key, signed message, and signature algorithm are as expected. |
| KEY_NOT_FOUND | F | The key is not found. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. |
| MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. | Use a media type that is accepted by Alipay+. |
| METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTPS method. | Ensure the HTTP method is POST. |
| NO_INTERFACE_DEF | F | API is not defined. | Check whether the request URL is correct. Ensure that the endpoint of the called API is correct. |
| NO_PAY_OPTIONS | F | No payment option exists. | N/A |
| PARAM_ILLEGAL | F | Illegal parameters. For example, non-numeric input, invalid date. | Check whether the request parameters, including the header parameters and body parameters, are correct and valid. For more information about the parameters of each API, see the Structure section of the specific API reference topic. |
| PROCESS_FAIL | F | A general business failure occurred. Do not retry. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. |
| REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. | Reduce the frequency of API calls. |
| UNKNOWN_EXCEPTION | U | An API call failed, which is caused by unknown reasons. | Try to recall the API. |

## Request

```json
{
  "userRegion": "PH",
  "paymentAmount": {
    "currency": "JPY",
    "value": "0"
  },
  "paymentFactor": {
    "isAgreementPayment": "true"
  },
  "settlementStrategy": {
    "settlementCurrency": "USD"
  },
  "merchant": {
    "referenceMerchantId": "M00000000001"
  },
  "env": {
    "terminalType": "APP",
    "osType": "IOS"
  }
}
```

## Response

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "paymentOptions": [
    {
      "paymentMethodType": "CONNECT_WALLET",
      "paymentMethodCategory": "WALLET",
      "enabled": "true",
      "brandName": "Alipay+™ Partner",
      "logo": {
        "logoName": "AlipayPlus",
        "logoUrl": "https://www.alipayplus.com/logo/20022222xxx.png"
      },
      "paymentOptionDetail": {
        "paymentOptionDetailType": "CONNECT_WALLET",
        "connectWallet": {
          "supportWallets": [
            {
              "walletName": "GCASH",
              "walletBrandName": "Gcash",
              "walletLogo": {
                "logoName": "Gcash",
                "logoUrl": "https://www.alipayplus.com/logo/gcash.png"
              },
              "walletRegion": "PH",
              "walletFeature": {
                "supportCodeScan": "true",
                "supportCashierRedirection": "true"
              }
            }
          ]
        }
      }
    }
  ]
}
```