How to identify Alipay+ codes

This topic goes through the actions that the Mobile Payment Provider (MPP) needs to take by using the following methods:

• Use the Alipay+ server SDK
• Use the Alipay+ code rules locally

Use the Alipay+ server SDK

To identify the order code by using the Alipay+ server SDK, follow the next steps.

Step 1: Initialize the Alipay+ server SDK

Call the ac.code.service.CodeIdentificationService#init API to initialize the Alipay+ server SDK.

Processing logic

When handling the result, follow the processing logic below:

• If result.resultStatus is S, the initialization is successful.
• If result.resultStatus is F or U, the initialization is blocked. The MPP can troubleshoot based on result codes and logs.

For more information about how to use the API (such as the parameter description), see CodeIdentificationService#init.

Sample

CodeIdentificationInitResult result = codeIdentificationService.init();
if (result.getResult().getResultStatus().equals("S")){
    // Initialization success.
} else {
    // Block the application startup and troubleshoot
}

Step 2: Identify the order code

Call the ac.code.service.CodeIdentificationService#identifyCode API to identify whether the code can be processed by Alipay+.

Processing logic

When handling the result, follow the processing logic below:

• If result.resultStatus is S, the code identification is successful. See the following list for details:

• If isSupported is true and postCodeMatchActionType is DECODE, the code can be processed by Alipay+. The MPP needs to send a request to Alipay+ to decode the code value.
• If isSupported is false, the code cannot be processed by Alipay+. The MPP needs to reject the code.

• If result.resultStatus is F, the code identification failed. The MPP can handle the result based on result codes.
• If result.resultStatus is U, unknown exceptions occur during the code identification and the MPP can check logs to view details. The MPP can try to call the API again later.

For more information about how to use the API (such as the parameter description), see CodeIdentificationService#identifyCode.

Sample

CodeIdentificationIdentifyRequest request = new CodeIdentificationIdentifyRequest();
request.setCodeValue("28100104df2342342****");
CodeIdentificationIdentifyResult result = codeIdentificationService.identifyCode(request);
if (result.getResult().getResultStatus().equals("S") && result.isSupported()){
    // the code should be processed by Alipay+
}
if (result.getResult().getResultStatus().equals("F"){
    // Please pay attention to resultCode
}

Use the Alipay+ code rules locally

Alipay+ code rules are a set of matching rules that are used to identify whether a code can be processed and decoded by Alipay+.

For MPPs who don't want to use the Alipay+ server SDK, they can call the inquiryCodeRules API that is provided by Alipay+ to obtain Alipay+ code rules. Then, the MPP saves and uses Alipay+ code rules locally to identify the code.

Complete the following steps to use the Alipay+ code rules locally.

Step 1: Inquire about the Alipay+ code rules

Before the code identification, the MPP server requests to obtain Alipay+ code rules by calling the inquiryCodeRules API. If the request succeeds, the MPP obtains and saves Alipay+ code rules on its server.

Processing logic

When handling the result, follow the processing logic below:

• If result.resultStatus is S, the inquiry is successful.
• If result.resultStatus is F or U, the inquiry is blocked. The MPP can troubleshoot the problem based on result codes.

For more information about how to use the API (such as the parameter description), see inquiryCodeRules.

Sample

The following samples show the request and response when the MPP calls the Alipay+ inquiryCodeRules API in the Cashier Payment scenario.

Request from the MPP to Alipay+

No request parameters need to be passed.

Response from Alipay+ to the MPP

{
  "codeRules": [
    {
      "codeMatchPattern": {
        "matchMethod": "PREFIX",
        "prefix": "http://qr.ap.dev.alipay.net/1630310122626"
      },
      "postCodeMatchAction": {
        "postCodeMatchActionType": "OPEN_URL",
        "urlConstructionMethod": "USE_DIRECTLY",
        "userAgent": "AlipayConnect"
      }
    },
    {
      "codeMatchPattern": {
        "matchMethod": "REGEX",
        "regex": "^https?:\\/\\/(qr-test-entry-code|app-cscan|vmp|1633984529766)\\.(eftpay|eftsolutions|o2pcn)\\.com(\\.(cn|hk))?\\/.*"
      },
      "postCodeMatchAction": {
        "postCodeMatchActionType": "OPEN_URL",
        "urlConstructionMethod": "USE_DIRECTLY",
        "userAgent": "AlipayConnect"
      }
    },
    {
      "codeMatchPattern": {
        "emvMatchRules": [
          {
            "extendedMerchantTag": "00",
            "extendedMerchantValue": "com.alipay",
            "isPrimitiveMerchant": "false"
          }
        ],
        "matchMethod": "EMVCO"
      },
      "postCodeMatchAction": {
        "emvUrlTag": "[26-51].01",
        "postCodeMatchActionType": "OPEN_URL",
        "urlConstructionMethod": "EXTRACT_URL_FROM_EMVCODE",
        "userAgent": "AlipayConnect"
      }
    },
    {
      "codeMatchPattern": {
        "emvMatchRules": [
          {
            "primitiveMerchantTag": "28",
            "isPrimitiveMerchant": "true"
          }
        ],
        "matchMethod": "EMVCO"
      },
      "postCodeMatchAction": {
        "emvUrlTag": "28.01",
        "postCodeMatchActionType": "OPEN_URL",
        "urlConstructionMethod": "EXTRACT_URL_FROM_EMVCODE",
        "userAgent": "AlipayConnect"
      }
    },
    {
      "codeMatchPattern": {
        "emvMatchRules": [
          {
            "extendedMerchantTag": "00",
            "extendedMerchantValue": "SG.COM.NETS",
            "isPrimitiveMerchant": "false"
          }
        ],
        "matchMethod": "EMVCO"
      },
      "postCodeMatchAction": {
        "dynamicUrlExpression": "http://rendertest.alipay.com/p/yuyan/180020010001195821/shop.html?region=SG&tntInstId=ALIPW3SG&codeValue=%s",
        "postCodeMatchActionType": "OPEN_URL",
        "urlConstructionMethod": "CONSTRUCT_DYNAMIC_URL",
        "userAgent": "AlipayConnect"
      }
    },
    {
      "codeMatchPattern": {
        "matchMethod": "PREFIX",
        "prefix": "http://qr.ap.dev.alipay.net/1633195255321"
      },
      "postCodeMatchAction": {
        "postCodeMatchActionType": "DECODE"
      }
    }
  ],
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  },
  "version": "6921"
}

Step 2: Update the Alipay+ code rules

To use Alipay+ code rules, the MPP needs to ensure that the code rules that are cached locally are in the latest version. Thus, it is necessary for the MPP to regularly update the code rules.

The following figure illustrates the process to update the code rules:

Figure 1. Process of updating code rules

The process consists of the following steps:

1. The MPP sets a timer to regularly trigger API calls, so as to inquire about Alipay+ code rules.

Note: The frequency of the API calls needs to be at least once per day.

2. The MPP calls the inquiryCodeRules API to obtain Alipay+ code rules.
3. The MPP server identifies whether the version of obtained Alipay+ code rules is consistent with that of Alipay+ code rules that are cached locally.

• If so, the MPP keeps Alipay+ code rules that are cached locally.
• If not, the MPP updates Alipay+ code rules that are cached locally to the latest version.

Step 3: Identify the code by matching Alipay+ code rules

When the user scans an order code, the MPP needs to identify whether the code can be decoded with Alipay+ code rules, and respectively take further actions.

The following figure illustrates the process:

Figure 2. Process of matching code rules

The process consists of the following steps:

1. The MPP server receives the code value.
2. The MPP server searches for and tries to match the code value with Alipay+ code rules, so as to identify whether the code can be decoded with these code rules. For more information, see How to match Alipay+ code rules.

• If so, the MPP server checks the value of postCodeMatchAction.postCodeMatchActionType as stated in the respective code rule that is returned in the inquiryCodeRules API, and takes further actions. For more information about what further actions need to be taken for different values, see Step 4: Handle the matching result.
• If not, the MPP server continues searching for Alipay+ code rules.

How to match Alipay+ code rules

Alipay+ code rules support the following three matching methods that are returned by Alipay+ for the codeRules.codeMatchPattern.MatchMethod parameter in the inquiryCodeRules API:

• PREFIX: to match by checking whether the prefix is matched
• REGEX: to match by using the regular expression
• EMVCO: to match by following the EMV code specifications

{
  "codeMatchPattern": {
    "matchMethod": "PREFIX",
    "prefix": "http://qr.ap.dev.alipay.net/1633195255321"
  },
  "postCodeMatchAction": {
    "postCodeMatchActionType": "DECODE"
  }
}

String codeValue = "";
if(codeValue.startsWith(codeMatchPattern.prefix)) {
    // do A+ decode
}

{
  "codeMatchPattern": {
    "matchMethod": "REGEX",
    "regex": "^https?:\\/\\/(qr-test-entry-code|app-cscan|vmp|1633984529766)\\.(eftpay|eftsolutions|o2pcn)\\.com(\\.(cn|hk))?\\/.*"
  },
  "postCodeMatchAction": {
    "postCodeMatchActionType": "DECODE"
  }
}

String codeValue = "";
Pattern pattern = Pattern.compile(codeMatchPattern.regex);
if(pattern.matcher(codeValue).matches()) {
    // do A+ decode
}

{
 "codeMatchPattern": {
  "emvMatchRules": [{
   "extendedMerchantTag": "00",
   "extendedMerchantValue": "com.alipay",
   "isPrimitiveMerchant": "false"
  }],
  "matchMethod": "EMVCO"
 },
 "postCodeMatchAction": {
  "postCodeMatchActionType": "DECODE"
 }
}

{ "matcherType": "EMVCO", "isPrimitiveMai": false, "merchantMaiRestrictions": { "00": "com.alipay", "01": "S<https://qr.kakaopay.com/281006>" } }

Step 4: Handle the matching result

If the code matches a certain Alipay+ code rule, the MPP needs to handle the matching result according to the code rule.

The following figure illustrates the process to handle the matching result:

Figure 3. Process of handling matching result

The process consists of the following steps:

1. The MPP server checks the value of postCodeMatchAction.postCodeMatchActionType in the respective code rule that is returned by Alipay+ in the inquryCodeRules API.

• If the value of postCodeMatchAction.postCodeMatchActionType is DECODE, the MPP server calls the userInitiatedPay API to send a decoding request to Alipay+. For more information about how to call this API, see Step 2: Decode the code.
• If the value of postCodeMatchAction.postCodeMatchActionType is OPEN_URL, the MPP server needs to open the URL. For more information about how to open the URL, see How to open the URL.

How to open the URL

If the value of postCodeMatchAction.postCodeMatchActionType is OPEN_URL, the MPP server needs to open the URL according to the value of postCodeMatchAction.urlConstructionMethod. For this parameter, valid values are:

• USE_DIRECTLY: to directly open the URL
• CONSTRUCT_DYNAMIC_URL: to construct a URL based on the dynamic URL expression returned by Alipay+ and open it
• EXTRACT_URL_FROM_EMVCODE: to extract the value of emvUrlTag to construct a URL and open it

USE_DIRECTLY

The following sample shows the code rule when the value of postCodeMatchAction.urlConstructionMethod is USE_DIRECTLY.

{
        "codeMatchPattern": {
            "matchMethod": "REGEX",
            "regex": "^https?:\\/\\/(qr-test-entry-code|app-cscan|vmp|1633984529766)\\.(eftpay|eftsolutions|o2pcn)\\.com(\\.(cn|hk))?\\/.*"
        },
        "postCodeMatchAction": {
            "postCodeMatchActionType": "OPEN_URL",
            "urlConstructionMethod": "USE_DIRECTLY",
            "userAgent": "AlipayConnect"
        }
    }

With such a code rule, the MPP can open the URL that is contained in the code value directly.

CONSTRUCT_DYNAMIC_URL

The following sample shows the code rule when the value of postCodeMatchAction.urlConstructionMethod is CONSTRUCT_DYNAMIC_URL.

{
        "codeMatchPattern": {
            "emvMatchRules": [{
                "extendedMerchantTag": "00",
                "extendedMerchantValue": "SG.COM.NETS",
                "isPrimitiveMerchant": "false"
            }],
            "matchMethod": "EMVCO"
        },
        "postCodeMatchAction": {
            "dynamicUrlExpression": "http://rendertest.alipay.com/p/yuyan/180020010001195821/shop.html?region=SG&tntInstId=ALIPW3SG&codeValue=%s",
            "postCodeMatchActionType": "OPEN_URL",
            "urlConstructionMethod": "CONSTRUCT_DYNAMIC_URL",
            "userAgent": "AlipayConnect"
        }
    }

With such a code rule, the MPP can run the following code to construct a URL and open it.

// codeValue that is sent by the MPP client
String encodeCodeValue = UrlEncoderUtil.encode(codeValue, "UTF_8");
Map<String, String> valuesMap = new HashMap<>();
valuesMap.put("codeValue", encodeCodeValue);
StrSubstitutor sub = new StrSubstitutor(valuesMap);
return sub.replace(baseUrl);

EXTRACT_URL_FROM_EMVCODE

The following sample shows the code rule when the value of postCodeMatchAction.urlConstructionMethod is EXTRACT_URL_FROM_EMVCODE.

{
        "codeMatchPattern": {
            "matchMethod": "REGEX",
            "regex": "^https?:\\/\\/(qr-test-entry-code|app-cscan|vmp|1633984529766)\\.(eftpay|eftsolutions|o2pcn)\\.com(\\.(cn|hk))?\\/.*"
        },
        "postCodeMatchAction": {
            "postCodeMatchActionType": "OPEN_URL",
            "urlConstructionMethod": "EXTRACT_URL_FROM_EMVCODE",
            "userAgent": "AlipayConnect"
        }
    }

With such a code rule, the MPP needs to extract the value of emvUrlTag to construct a URL and open it. For more information about EMV QR codes, see EMVCo website or📎EMV QRCPS.pdf