Alipay+ DocsAlipay+ Docs

Request JSON data from the Alipay+ CDN server

Alipay+ allows you to request JSON data from the Alipay+ CDN server and parse JSON to obtain Alipay+ payment method information, which incldues:

  • whether the Ailpay+ payment method is available
  • if available, one or multiple Alipay+ logo assets and detailed logo information, including the logo width, logo height, and logo URLs
  • if available, the Alipay+ promotion campaign names in multiple languages

With such information, you need to display Alipay+ as a payment method correctly, including:

  • display the Alipay+ logo only when the Alipay+ payment method is available
  • display the Alipay+ logo by using the logo URL parsed from JSON
  • display the promotion campaign name next to the Alipay+ logo if the promoNames parameter exists in JSON

Construct the CDN URL

To request the JSON data that contains the Alipay+ payment method information, you need to construct a CDN URL as follows:

  • Production environment: https://resource.alipayplus.com/prod/<acquirerId>/sha256(<referenceMerchantId>)/<productCode>/<paymentCurrency>/<userRegion>/<logoPattern>/alipayplus.json
  • Sandbox environment: https://developers.alipayplus.com/cdn/sandbox/<acquirerId>/sha256(<referenceMerchantId>)/<productCode>/<paymentCurrency>/<userRegion>/<logoPattern>/alipayplus.json

Note: All parameters in the CDN URL are required. See the following table for details about how to specify values for the parameters.

Request parameters

The following table lists the request parameters in the CDN URL.

Parameter

Type

Description

acquirerId

String(64)

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

Important:

Specify different values for this parameter in the production and sandbox environment as follows:

  • Production environment: Specify the Participant ID that is provided by your solution architect.
  • Sandbox environment: Specify the Participant ID that is displayed on the Settings page under the Sandbox tab of the Alipay+ Developer Center. For more information, see Develop in sandbox.

referenceMerchantId

String(64)

The unique ID that is assigned by the ACQP to identify a merchant. The value of this parameter must be SHA256 encrypted to convert special characters.

productCode

String(32)

The type of payment product that is supported by the merchant.

Valid values are:

  • CASHIER_PAYMENT

paymentCurrency

String(3)

The payment currency, also known as transaction currency, that is supported by the merchant. The value of this parameter must be an alphabetic code that follows the ISO 4217 standard, for example, "EUR" for Euros.

userRegion

String(14)

This parameter is reserved for further use. Set the value to defaultregion.

logoPattern

String(32)

The pattern of the logo, such as P1-WEB-01. The value consists of the following three parts:

  • The layout of the logo. Valid values are:
    • P1: indicates that the Alipay+ logo is located on the left of wallet logos.
    • P2: indicates that the Alipay+ logo is above wallet logos.
  • The terminal type that the logo is applied to. Valid values are WEB and APP.
  • Custom field with a maximum length of 10 characters. The default values are sequential numbers starting from01.

Note: If you do not want to filter logos, set the value of this parameter to defaultlogo and all preconfigured logos are returned.

Response parameters

The following table lists the response parameters contained in JSON data.

Parameter

Type

Required

Description

enabled

Boolean

M

Specifies whether the Alipay+ payment method is available.

logos

Array<Logo>

M

The list of logos.

promoNames

Array<String(512)>

O

The list of the promotion names in JSON format. The key is the language, such as en_US, while the value is the promotion name, such as RM1 Voucher.

Commonly used values of the languages include:

  • zh_CN: Simplified Chinese
  • zh_HK: Traditional Chinese
  • en_US: English
  • ko_KR: Korean
  • fil_PH: Filipino
  • ms_MY: Malay
  • id_ID: Indonesian
  • th_TH: Thai

brandName

String (128)

M

The Alipay+ brand name.

Logo

Parameter

Type

Required

Description

logoName

String(128)

M

The name of the logo.

logoUrl

String(2048)

M

The URL of the logo.

logoPattern

String(32)

M

The pattern of the logo, such as P1-WEB-01.

logoWidth

String(12)

M

The width of the logo. Unit: px.

logoHeight

String(12)

M

The height of the logo. Unit: px.

Sample

Sample CDN URL

https://resource.alipayplus.com/prod/A1112TEST0000000/82c67417922f7c946504b2d9faff39c260539213e5a4effbb561396fccde3498/CASHIER_PAYMENT/USD/defaultregion/P2-WEB-TypeD/alipayplus.json

Sample response

JSON data without promotion information:

copy
{
  "enabled": true,
  "logos":[
      {
        "logoName": "Alipay+",
        "logoUrl": "https://resource.alipayplus.com/prod/A1112TEST0000000/82c67417922f7c946504b2d9faff39c260539213e5a4effbb561396fccde3498/CASHIER_PAYMENT/USD/defaultregion/P2-WEB-TypeD/alipayplus.png",
        "logoPattern": "P2-WEB-TypeD",
        "logoWidth": "912",
        "logoHeight": "120"
      }
    ],
  "brandName": "Alipay+"
}

JSON data with promotion information:

copy
{
  "enabled": true,
  "logos":[
      {
        "logoName": "Alipay+",
        "logoUrl": "https://resource.alipayplus.com/prod/A1112TEST0000000/82c67417922f7c946504b2d9faff39c260539213e5a4effbb561396fccde3498/CASHIER_PAYMENT/PHP/defaultregion/P2-WEB-TypeD/alipayplus.png",
        "logoPattern": "P2-WEB-TypeD",
        "logoWidth": "912",
        "logoHeight": "120"
      }
    ],
   "promoNames": [
    "{\"en_US\":\"RM1 Voucher\", \"zh_CN\":\"1元 红包\"}"
  ],
  "brandName": "Alipay+"
}

After the CDN URL is constructed, you can call the Alipay+ CDN server from your server side or client side. The consultation workflow differs depending on how you call the CDN server.

Call from server side

The following figure illustrates the workflow of how to call the Alipay+ CDN server from your server side.

cashier_server.jpg

Figure 1: Call Alipay+ CDN server from server side

The workflow contains the following major steps:

  1. When the user places an order, you need to obtain the payment method information as follows:

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

1.2 Your server side constructs a CDN URL to obtain information about the Alipay+ payment method from the Alipay+ CDN server (Step 6).

  1. Alipay+ CDN server returns a response that includes the following information to your server side (Step 7):
    • If the value of the enabled parameter is true, the Alipay+ logo, brand name, and promotion information are returned in JSON.
  1. Your server side constructs the payment method list and returns it to your client side (Step 8-10).
  2. Your client side renders the payment method page by using the result returned by your server side (Step 11).

Sample

The following sample shows how to request JSON data from your server side.

copy
private static String CDNURL_PREFIX  = "https://resource.alipayplus.com/prod/";
private static String ACQUIRER_ID = "A1112TEST0000000";
private static String MERCHANT_ID = "testMerchant";
private static String PRODUCT_CODE     = "CASHIER_PAYMENT";


//Specify logoPattern to request Alipay+ logo and promotion info
public LogoAndPromotion fetchLogoAndPromotion(String logoPattern, String paymentCurrency) {
    
    LogoAndPromotion result = new LogoAndPromotion();   
    
    // 1. Construct a URL and visit the URL
    String url = CDNURL_PREFIX + 
        String.join("/", ACQUIRER_ID, getSHA256Str(MERCHANT_ID),
                    PRODUCT_CODE, paymentCurrency, "defaultregion", logoPattern, "alipayplus.json");
        
    // 2. Use the GET method to read file 
    // Return an empty string when 404 not found or 500 network error occurs
    String rtnJson = HttpClientGet(url);

    // 3. If no JSON file is found with the URL, this indicates that the Alipay+ payment method is unavailable 
    if (Objects.isNull(rtnJson) || rtnJson.isEmpty()) {
        result.setEnabled(false);
        return result;
    }

    JSONObject document = JSON.parseObject(rtnJson);

    // 4. If the enabled field is false in JSON, this indicates no payment method is available
    if (Objects.isNull(document.getBoolean("enabled")) || !document.getBoolean("enabled")) {
        result.setEnabled(false);
        return result;
    }
    result.setEnabled(true);

    // 5. Parse JSON to obtain logo 
    List<LogoAndPromotion> logos = document.getObject("logos", new TypeReference<List<LogoAndPromotion>>(){});
    
    if(logos.size >0){
        result.setLogoName(logos.get(0).getLogoName());
        result.setLogoPattern(logos.get(0).getLogoPattern());
        result.setLogoWidth(logos.get(0).getLogoWidth());
        result.setLogoHeight(logos.get(0).getLogoHeight());
    }
    //6. Process promotion info
    // Get the promoNames field from JSON
    JSONArray promoNames = document.getJSONArray("promoNames");
    result.setPromoNames(fetchPromotionMap(promoNames);
    return result;
}


private Map<String, String> fetchPromotionMap(JSONObject promoNames) {
    Map<String, String> promoMap = null;
    // If the field exists and is not empty, this indicates that promotion info exists
    if (Objects.nonNull(promoNames) && promoNames.size() > 0) {
        promoMap = new HashMap<>();
        // Parse promotion info to Map objects, where the key indicates the language and the value indicates the promotion campagin name
        JSONObject promos = JSON.parseObject(promoNames.getString(0));
        for (Map.Entry<String, Object> entry : promos.entrySet()) {
            promoMap.put(entry.getKey(), (String) entry.getValue());
        }
    }
    return promoMap;
}    



public class LogoAndPromotion {
    private boolean enabled;
    private String logoName;
    private String logoUrl;
    private String logoPattern;
    private String logoWidth;
    private String logoHeight;
    private Map<String, String> promoNames;
    // Getter and Setter......
}

Call from client side

The following figure illustrates the workflow of how to call the Alipay+ CDN server from your client side.

cashier_client.jpg

Figure 2: Call Alipay+ CDN server from client side

The workflow contains the following major steps:

  1. When the user places an order, you need to obtain the payment method information as follows:

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

1.2 Your client side constructs a CDN URL to obtain information about the Alipay+ payment method from the Alipay+ CDN server (Step 6).

  1. Alipay+ CDN server returns a response that includes the following information to your client side (Step 7):
    • If value of the enabled parameter is true, the Alipay+ logo, brand name, and promotion information are returned in JSON.
  1. Your client side renders the payment method page by using the result returned by your server side and Alipay+ (Step 8).

Sample

The following sample shows how to request JSON data from your client side.

copy

const CASHIER_PAYMENT = 'CASHIER_PAYMENT';
const DEFAULT_LOGO_PATTERN_PARAMS = 'defaultlogo';
const DEFAULT_USER_REGION_PARAMS = 'defaultregion';
const URL_PREFIX = 'https://resource.alipayplus.com/prod';

const acquirerId = 'A1112TEST0000000';
const merchantId = 'testMerchant';


const inquirePaymentOption = (paymentCurrency, userRegion, logoPattern) => {
  // 1. Construct the CDN URL
  const url = `${URL_PREFIX}/${acquirerId}/${genSHA256(merchantId)}/${CASHIER_PAYMENT}/${paymentCurrency}/${userRegion || DEFAULT_USER_REGION_PARAMS
  }/${logoPattern || DEFAULT_LOGO_PATTERN_PARAMS}/alipayplus.json`;
  // 2. Send request
  return fetch(url).then(async (res) => {
    // 3. Request is successful
    if (res.ok) {
      const data = await res.json();
      return data;
    } else if (String(res.status) === '404') {
      // Exception: No payment option is available
      throw new Error('NO_PAY_OPTIONS')
    } else {
      // Exception: network error
      throw new Error('NETWORK_ERROR');
    }
  }, () => {
    // Exception: network error
    throw new Error('NETWORK_ERROR');
  });
};