Alipay+Alipay+

How to consult payment method information

To render the payment method or add 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 Web/WAP SDK (Alipay+ SDK for short) to consult the payment method information.

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

Method

Terminal type

Web

WAP

App

Use the consultPayment API




Integrate the Alipay+ 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.

call consultPayment to consult EN.jpg

Figure 1. Consult payment method info with consultPayment API

The workflow contains the following major steps:

  1. When the user starts the binding process, your server side calls the Alipay+ consultPayment API (Step 5).
  2. Alipay+ returns a response that includes the following information (Step 6):
    • 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.
  1. Your client side renders the payment method page or add payment method page by using the result returned by Alipay+ (Step 10).

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 are configured with 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 succeeds. The

paymentOptions parameter that contains the Alipay+ payment method information is returned in the response.

Render the payment method page or add payment method 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

  1. The ACQP sends a request to Alipay+.
copy
{
    "userRegion": "PH",
    "paymentAmount": {
        "currency": "JPY",
        "value": "0"
    },
    "paymentFactor": {
        "isAgreementPayment": "true",
        "presentmentMode": "UNIFIED",
    },
    "settlementStrategy": {
        "settlementCurrency": "USD"
    },
    "merchant": {
        "referenceMerchantId": "M00000000001"
    },
    "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元 红包\"}"]

  }]
}

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

Method 2: Integrate the Alipay+ SDK

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

call WebWAP SDK to consult EN.jpg

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

The workflow contains the following major steps:

  1. When the user starts the binding process, 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 2-4);

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

Note: You may implement Step 2 and Step 5 concurrently.

  1. Alipay+ returns a response that includes the following information (Step 7-8):
    • If the API call is accepted and the value of the authorizationOption.enabled parameter is true, the Alipay+ logo, brand name, and promotion information are specified on the authorizationOption parameter.
  1. Your client side renders the payment method page or add payment method page by using the result returned by your server side and Alipay+ (Step 9).

Processing logic

When you call the inquireAuthorizationOption 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 authorizationOption.enabled parameter is false, this indicates that the Alipay+ payment method is not available for this transaction.
    • If the value of the authorizationOption.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 or add 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 are configured with 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',
});

inquireAuthorizationOption()

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

copy
alipayPlus.inquireAuthorizationOption({
  paymentCurrency: 'PHP',
}).then((authorizationOption) => {
  // show payment method page or add payment method page with Alipay+ payment method
}, (error) => {
  // handle error
});

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