How to consult payment method information

To render the payment method page with the information about the Alipay+ payment method, your client side needs to consult the information firstly. This chapter introduces how to consult the Alipay+ payment method information, including the Alipay+ logo, brand name, and promotion information.

Note: The Alipay+ logo mentioned in this topic refers to:
the default Alipay+ logo that displays only the Alipay+ brand if no aggregated logo is preconfigured.
aggregated logos that display both the Alipay+ brand and other wallet brands if aggregated logos are preconfigured.

In general, Alipay+ provides two methods for you to consult the payment method information:

Method 1: Use the consultPayment API

Your server side calls the consultPayment API to consult the payment method information.

Method 2: Integrate the Alipay+ SDK

Your client side integrates the Alipay+ ACQP Client SDK (Alipay+ SDK for short) to consult the payment method information. Alipay+ SDK provides two SDK editions: Mobile SDK and Web/WAP SDK.

The following table shows the terminal types that are supported by these methods.

Method		Terminal type
Method		Web	WAP	App
Use the consultPayment API		✅	✅	✅
Integrate the Alipay+ SDK	Mobile SDK	🔲	🔲	✅
Integrate the Alipay+ SDK	Web/WAP SDK	✅	✅	✅

Method 1: Use the consultPayment API

The following figure illustrates the main workflow of how to consult the payment method information with this method.

consultPayment接口.jpg

Figure 1. Consult payment method info with consultPayment API

The workflow contains the following major steps:

When the user places an order, your server side calls the Alipay+ consultPayment API (Step 6).
Alipay+ returns a response that includes the following information (Step 7):

The acceptance result of the consultPayment API, which is specified on the result parameter.
If the API call is accepted and the value of the paymentOption.enabled parameter is true, the Alipay+ logo, brand name, and promotion information are specified on the paymentOptions parameter.

Your client side renders the payment method page by using the result returned by Alipay+ (Step 11).

Processing logic

When you call the consultPayment API, take the following things into consideration:

How to specify the input parameters

Set the value of paymentFactor.presentmentMode parameter to UNIFIED.

How to handle the output parameters

If the value of the result.resultCode parameter is SUCCESS and the value of the paymentOption.enabled parameter is false, this indicates that the Alipay+ payment method is not available for this transaction.
If the value of the result.resultCode parameter is SUCCESS and the value of the paymentOption.enabled parameter is true, you can obtain the information about the Alipay+ payment method from the paymentOptions parameter.

If no aggregated logo is preconfigured, the default Alipay+ logo is returned on the paymentOption.logos parameter. Your client side needs to display the default Alipay+ logo along with the promotion information (if any) returned on the paymentOption.promoNames parameter.
If aggregated logos are preconfigured, one or more aggregated logos are returned on the paymentOption.logos parameter.

The aggregated logos are returned based on the currency specified on the paymentAmount.currency parameter if different aggregated logos are configured for different currencies. If no aggregated logo matches the currency, the default aggregated logo is returned.
If the aggregated logos include the promotion tag, your client side can directly display these logos; otherwise, your client side needs to display the aggregated logos along with the promotion information (if any) returned on the paymentOption.promoNames parameter.

The Alipay+ logo, brand name, and promotion information returned to your client side must be the same as the ones returned in the response of the consultPayment API.
You might receive different results from Alipay+. Follow the instructions below to handle the result:

result.resultStatus	result.resultCode	Consultation 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	...	Consultation fails.	Take actions according to the error message in the result.resultCode parameter.
U	...	Consultation is in processing.	Retry the same request. Ensure that the parameters are the same as the previous one.
No result received		Unknown.	Retry the same request. Ensure that the parameters are the same as the previous one.

Samples

The ACQP sends a request to Alipay+.

copy
{
  "paymentAmount": {
    "currency": "JPY", 
    "value": "100"
  }, 
  "paymentFactor": {
    "presentmentMode": "UNIFIED",
    "isCashierPayment": "true",
    "isInStorePayment": "false"
  },
  "settlementStrategy": {
    "settlementCurrency": "USD"
  },
  "merchant": {
    "referenceMerchantId": "M00xxxxx0001"
  },
  "env": {
      "terminalType":"APP",
      "OsType":"IOS"
   }
}

2.1 Alipay+ returns a response to the ACQP when no aggregated logo is preconfigured.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "paymentOptions": [{
    "paymentMethodType": "CONNECT_WALLET",
    "enabled": "true",
    "brandName": "Alipay+",
    "logos":[{
            "logoName": "Alipay+",
            "logoUrl": "https://cdn.marmot-cloud.com/storage/aplus-checkout-prod/icon/prod/CONNECT_WALLET.png",
            "logoPattern": "default",
            "logoWidth": "810",
      "logoHeight": "190"
        }],
    "promoNames": ["{\"en_US\":\"RM1 Voucher\", \"zh_CN\":\"1元 红包\"}"]

  }]
}

2.2 Alipay+ returns a response to the ACQP when aggregated logos are preconfigured.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "paymentOptions": [{
    "paymentMethodType": "CONNECT_WALLET",
    "enabled": "true",
    "brandName": "Alipay+",
    "logos":[{
            "logoName": "Alipay+",
            "logoUrl": "https://cdn.marmot-cloud.com/storage/aplus-checkout-prod/icon/prod/P1-WEB-01-20220421.png",
            "logoPattern": "P1-WEB-01",
            "logoWidth": "810",
      "logoHeight": "190"
        }, {
            "logoName": "Alipay+",
            "logoUrl": "https://cdn.marmot-cloud.com/storage/aplus-checkout-prod/icon/prod/P2-MOBILE-01-20220421.png",
            "logoPattern": "P2-MOBILE-01",
            "logoWidth": "640",
      "logoHeight": "320"
        }],
    "promoNames": ["{\"en_US\":\"RM1 Voucher\", \"zh_CN\":\"1元 红包\"}"]

  }]
}

More information

For more information about how to use the API parameters, see consultPayment.

Method 2: Integrate the Alipay+ SDK

The Alipay+ SDK consists of the mobile SDK and Web/WAP SDK. The consultation workflow differs depending on the SDK edition that you use.

Use the mobile SDK

The following figure illustrates the main workflow of how to consult the payment method information by using the mobile SDK.

consultPayment by Mobile SDK.jpg

Figure 2. Consult payment method info with mobile SDK

The workflow contains the following major steps:

When the user places an order, your client side needs to obtain the payment method information as follows:

1.1 Call your server side to obtain the payment method list (Step 1-5);

1.2 Call the inquirePaymentOption API provided by the mobile SDK to obtain information about the Alipay+ payment method with the params parameter and the completionHandler parameter (Step 6).

Alipay+ returns a response that includes the following information (Step 8-9):

If the API call is accepted and the value of the paymentOption.enabled parameter is true, the Alipay+ logo, brand name, and promotion information are specified on the paymentOption parameter.

Your client side renders the payment method page by using the result returned by your server side and Alipay+ (Step 10).

Processing logic

When you call the inquirePaymentOption API, take the following things into consideration:

Prerequisites

Call the setConfiguration API to set up the SDK with the following parameters before you use other APIs: merchantId, acquirerId, language, and envType.
The merchantId must be the same as the merchantInfo.referenceMerchantId that is specified in the registration API request.
The acquirerId is assigned by Alipay+ to identify an ACQP.

How to handle the output parameters

If the value of the paymentOption.enabled parameter is false in the callback, this indicates that the Alipay+ payment method is not available for this transaction.
If the value of the paymentOption.enabled parameter is true in the callback, this indicates that the Alipay+ payment method is available and you need to display the Alipay+ logo, brand name, and promotion information (if any) on the payment method page.

If no aggregated logo is preconfigured, the default Alipay+ logo is returned. You need to display the default Alipay+ logo along with the promotion information (if any).
If aggregated logos are preconfigured, one or more aggregated logos are returned.

The aggregated logos are returned based on the currency specified in the input parameter. If no aggregated logo matches the currency, the default aggregated logo is returned.
If the aggregated logos include the promotion tag, you can directly display these logos; otherwise, you need to display the aggregated logos along with the promotion information (if any).

Samples

setConfiguration
The following sample code shows how to call the setConfiguration API.

iOS

copy
IAPConfiguration *configuration = IAPConfiguration.new;
configuration.envType = @"PROD";
configuration.acquirerId = @"xxx";
configuration.merchantId = @"yyy";
configuration.language= @"zzz";

[[AlipayPlusClient shared] setConfiguration:configuration];

Android

copy
IAPConfiguration configuration = new IAPConfiguration();
configuration.envType = "SANDBOX";
configuration.acquirerId = "XXX";
configuraiton.merchantId = "YYY";
configuration.language = "ZZZ";

AlipayPlusClient.setConfiguration(configuration);

inquirePaymentOption

The following sample code shows how to call the inquirePaymentOption API.

iOS

copy
IAPInquirePaymentOptionParams *params = IAPInquirePaymentOptionParams.new;
params.paymentCurrency = @"PHP";
[[AlipayPlusClient shared] inquirePaymentOptionWithParams:params 
completionHandler:^(IAPPaymentOption *paymentOption, NSError *error) {
if (!error && paymentOption.enabled) {
// show cashier page with Alipay+ payment method
} else {
// show cashier page with no Alipay+ payment method
}
}

Android

copy
IAPInquiryPaymentOptionParams params = new IAPInquiryPaymentOptionParams();
params.paymentCurrency = "PHP";
AlipayPlusClient.inquiryPaymentOption(context, params, new IAPInquiryPaymentCallback() {

    @override
    public void onSuccess(IAPPaymentOption paymentOption) {

        //show cashier page with Alipay+ payment method
    
    }
    
    public void onFailure(String errorCode, String errorMessage) {
    
        //show cashier page with no Alipay+ payment method
    
    }

});

More information

For more information about how to consult the payment method information by using the mobile SDK, see the following topics:

Use the Web/WAP SDK

The following figure illustrates the main workflow of how to consult the payment method information by using the Web/WAP SDK.

consultPayment by JS SDK.jpg

Figure 3. Consult payment method info with Web/WAP SDK

The workflow contains the following major steps:

When the user places an order, your client side needs to obtain the payment method information as follows:

1.1 Call your server side to obtain the payment method list (Step 1-5);

1.2 Call the inquirePaymentOption API provided by the Web/WAP SDK with the paymentCurrency parameter (Step 6).

Alipay+ returns a response that includes the following information (Step 8-9):

If the API call is accepted and the value of the paymentOption.enabled parameter is true, the Alipay+ logo, brand name, and promotion information are specified on the paymentOption parameter.

Your client side renders the payment method page by using the result returned by your server side and Alipay+ (Step 10).

Processing logic

When you call the inquirePaymentOption API, take the following things into consideration:

Prerequisites

Call the AlipayPlus.create() method of the Web/WAP SDK with the following parameters to create an instance during system initialization: merchantId, acquirerId, language, and envType.
The merchantId must be the same as the merchantInfo.referenceMerchantId that is specified in the registration API request.
The acquirerId is assigned by Alipay+ to identify an ACQP.

How to handle the output parameters

If the value of the paymentOption.enabled parameter is false, this indicates that the Alipay+ payment method is not available for this transaction.
If the value of the paymentOption.enabled parameter is true, this indicates that the Alipay+ payment method is available and you need to display the Alipay+ logo, brand name, and promotion information (if any) on the payment method page.

If no aggregated logo is preconfigured, the default Alipay+ logo is returned. You need to display the default Alipay+ logo along with the promotion information (if any).
If aggregated logos are preconfigured, one or more aggregated logos are returned.

The aggregated logos are returned based on the currency specified in the input parameter. If no aggregated logo matches the currency, the default aggregated logo is returned.
If the aggregated logos include the promotion tag, you can directly display these logos; otherwise, you need to display the aggregated logos along with the promotion information (if any).

Samples

AlipayPlus.create()

The following sample shows how to call the AlipayPlus.create() method:

copy
const alipayPlus = AlipayPlus.create({
  acquirerId: 'xxx',
  merchantId: 'yyy',
  language: 'en_US',
  envType: 'SANDBOX',
});

inquirePaymentOption()

The following sample shows how to call the inquirePaymentOption() API:

copy
alipayPlus.inquirePaymentOption({
  paymentCurrency: 'PHP',
}).then((paymentOption) => {
  // show cashier page with Alipay+ payment method
});

More information

For more information about how to consult the payment method information by using the Web/WAP SDK, see Alipay+ ACQP Web/WAP SDK interfaces.