Alipay+ DocsAlipay+ Docs

Release Notes

Version 1.5.1

Release date: 2024/02/29

Enhanced features

  • Modified the maximum length of the codeValue parameter in the prepare API from 64 characters to 2048 characters.

Document improvements

  • Deleted the misrepresentation that ECC256 is a supported signature algorithm in constructing API request headers and API response headers, retaining the RSA256 algorithm, which refers to SHA256withRSA. For more information, see API Reference.
  • Reorganized the Before you begin section in the Bind the user account chapter of the Auto Debit integration guide to make it more logical.
  • Added an FAQ specifying the usage of the API endpoint in both the production and sandbox environments. For more information, see Integration and acceptance.

Version 1.5.0

Release date: 2023/12/29

Enhanced features

  • Updated the integration of Merchant-presented Mode Payment (MPM) as follows:
    • Added the actionForm object to the userInitiatedPay API, which contains the actionForm.actionType and actionForm.sdkActionPayload parameters.
    • Added the handleAction API to the Alipay+ Client SDK. For more information, see either of the following documents:
    • Updated the definitions of the payCompletionHandle parameter in the decode API of Alipay+ Client SDK. For more information, see either of the following documents:

Document improvements

Version 1.4.2

Release date: 2023/10/31

Enhanced features

  • Added the preload API to the Alipay+ MPP Client SDK, which enables page loading acceleration for Merchant-presented Mode Payment. To utilize the preload API, you need to integrate components in your SDK. For more information, see:
  • Added a limitation for the MPP to verify the paymentCodeRegion parameter in the pay API for the User-presented Mode Payment scenario.
  • Updated Alipay+ brand mark and page detail requirements in the product introduction of User-presented Mode payment and Merchant-presented Mode Payment.
  • Changed the e-mail address for Alipay+'s after-sales service from connect_support@service.alipay.com to overseas_support@service.alibaba.com.

Document improvements

    • The exchange rates are not always greater than or equal to 1.
    • The order currency can be displayed either before or after the user's payment currency.

Similar descriptions are also added to the quoteCurrencyPair and quotePrice fields because exchange rates are transmitted via API in the preceding formats. For more information, see API Reference.

  • Added a note that all amount values in the reconciliation reports are provided in the smallest unit of the corresponding currency without decimal places. For more information, see Reports and reconciliation tasks.

Version 1.4.1

Release date: 2023/08/31

Enhanced features

  • Added a requirement that MPPs need to display the merchant name in multiple languages on the Payment Confirmation page, the Payment Result page, and the Transaction Detail page for Merchant-presented Mode Payment, and on the Payment Result page and the Transaction Detail page for User-presented Mode Payment.
  • Added the sandbox report directories to the Download reports chapter in Reconcile.
  • Added the acDecodeConfig.params request parameter to the launch API, which is used in the Merchant-presented Mode Payment scenario. Of which, forceHttps.acDecodeConfig.params can be used to require Alipay+ MPP Client SDK to redirect the user to the merchant page via an HTTPS URL by replacing http:// with https:// in case of an HTTP URL.
  • For Alipay+ Server SDK:
      • ac.route.remote-identify-url
      • ac.route.http.identify.socket-timeout
      • ac.route.http.identify.connect-timeout
      • ac.route.http.identify.connection-request-timeout

For more information, see Quickstart.

    • Added the log keyword [AC_SDK][INVALID_REMOTE_IDENTIFICATION_RESULT] for troubleshooting. For more information, see Troubleshooting.
  • Added the codeRules.extendInfo response parameter to the inquiryCodeRules API in API Reference.

Document improvements

  • Removed the value U from the value list of the paymentResult.resultStatus parameter in the notifyPayment API.

Version 1.4.0

Release date: 2023/06/30

New features

  • Added Alipay+ availability notification functionality that enables the MPP to inform the users of Alipay+ availability when the user is abroad in a location where Alipay+ is available. For more information, see Notify users of Alipay+ availability.
  • Added the ability for the MPP to obtain logos of acceptance marks. For more information, see Obtain logos of acceptance marks in the User-presented Mode Payment integration guide and Render the Scan page in the Merchant-presented Mode Payment integration guide.
  • Added the CANCEL_WINDOW_EXCEED result code for you to specify the scenario where the cancelation failed because the cancelation window is closed. For more information, see the cancelPayment API specification.

Enhanced features

  • Updated the page detail requirements for User-Presented Mode Payment as follows and user experience design accordingly. For more information, see the User-Presented Mode Payment product introduction.
    • Added requirements for displaying the brand mark and the acceptance mark on the Payment Code page.
    • Added an upgraded version of the Payment Code page where the region selector and exchange rate are displayed. If the number of regions/countries takes up over two mobile screens, the regions/countries must be listed alphabetically.
    • Added the requirement that the payment amount and order amount must be both displayed on the Payment Result page.
    • Added the favorable exchange rate provided by Alipay+ on the Payment Result page.
    • Removed options to use a button or a dropdown list as an entry to switch to the Alipay+ code on the Payment Code page.
  • Updated the page detail requirements for Merchant-presented Mode Payment as follows and user experience design accordingly. For more information, see the Merchant-presented Mode Payment product introduction.
    • Added requirements for displaying acceptance marks on the Scan page.
    • Added the favorable exchange rate provided by Alipay+ on the Payment Confirmation page and Payment Result page.
    • Added the requirement that the payment amount and order amount must both be displayed on the Payment Result page.

Deprecated features

Document improvements

  • Updated the Reconcile documentation as follows to improve accuracy and consistency:
    • Corrected the field name feeSettleAmountValue to feeSettlementAmountValue in the sample fee reports of the Fee Report topic.
    • Unified the service fee rates to 1% and interchange fee rates to 3% in the sample reconciliation reports of the Perform reconciliation and Reports topics.
  • Removed the authExpiryTime parameter from the response of the pay API specification.

Version 1.3.0

Release date: 2023/04/28

New features

  • Added support for account binding by scanning a QR code rendered on the merchant Web page in the Auto Debit scenario. To support this feature, added the codeValue and codeExpireTime parameters to the prepare API. For more information, see the following topics:
  • Added the REGULATION_RESTRICTION result code for you to specify the scenario where the payment failed due to regulatory restriction. For more information, see the following API specifications:
  • Added the paymentCodeRegion child parameter to the paymentMethod.paymentMethodMetaData parameter for the pay API.

Enhanced features

  • Changed the openId parameter in the CodeIdentificationService#identifyCode API from Required to Optional.
  • Changed the maximum length of the customerBelongsTo parameter in the prepare API from 16 to 32 characters.
  • Updated the Alipay Server SDK in the following aspects:
    • Changed the mode of initiating the SDK (specified by the ac.route.init-route-config-level property) from REMOTE or STORAGE to PRESET. For more information, see Quickstart.
    • Added support for configuring the log path (specified by the ac.log.path property). For more information, see Log file locations.

Document improvements

  • Updated the Idempotency topic in the API reference to include key parameters that are checked for consistency in idempotency control.
  • Added the Timeout topic to the API reference to introduce the timeout values set by Alipay+ for each API request and how to set the timeout value when calling Alipay+.
  • Added the How are the different amounts calculated section to illustrate how Alipay+ calcluates different amounts in the following API specifications:
  • Added the Support Alipay+ marketing activities topic to the Best practices guide to introduce how to handle marketing information and support Alipay+ in performing risk evaluation.
  • Refined the workflow diagram of making a payment and its description in the Cashier Payment integration guide. For more information, see Make a payment.

Version 1.2.1

Release date: 2023/02/28

New features

  • Released the getPaymentCode API for MPPs to obtain payment codes from Alipay+ in the User-presented Mode Payment scenario. For more information, see the getPaymentCode API specification and User-presented Mode Payment integration guide.

Enhanced features

  • Modified the maximum length of the order.merchant.referenceMerchantId and order.merchant.store.referenceStoreId parameters in the pay and userInitiatedPay APIs from 64 characters to 32 characters.
  • Updated the code rule to identify EMV codes in the Cashier Payment and Merchant-presented Mode Payment scenarios. For more information, see the following documents:

Document improvements

  • Corrected the endpoint of the inquiryCodeRules API from /aps/api/v1/payments/inquiryCodeRules to /aps/api/v1/codes/inquiryCodeRules. For more information, see the inquiryCodeRules API specification.
  • Added a note in the Reconcile documentation to emphasize that Alipay+ reports prevail when discrepancies exist due to payment status inconsistencies between the MPP system and the Alipay+ system. For more information, see Process overview of the Perform reconciliation topic.
  • Added troubleshooting instructions about signature validation to the message transmission section of the FAQ documentation.
  • Removed the enumeration value MINI_APP from the terminalType parameter in the prepare API specification because currently authorization cannot be initiated via mini apps.

Version 1.2.0

Release date: 2022/12/30

New features

  • Provide accelerated domain names to enable faster access to Alipay+ APIs. For more information, see Environment.

Enhanced features

    • For Merchant-presented Mode Payment: Added the design requirements and suggestions for the Payment confirmation page, Payment result page, and Transaction Detail page.
    • For User-presented Mode Payment:
      • Added the design requirements and suggestions for the Alipay+ payment code page, Payment result page, and Transaction Detail page.
      • Added optional design standards in terms of country/region list display, QR code and barcode design, screen brightness, and dropdown list design of the Alipay+ QR code entrance.
    • Removed the User Experience Guidelines because the content is merged into product introductions.
  • A new set of design requirements and suggestions for the Transaction Detail Page is added for Cashier Payment and Auto Debit. For more information, see the Page detail requirements of the product introductions for Cashier Payment and Auto Debit.
  • Changed the order.merchant.merchantDisplayName parameter in the pay and userInitiatedPay APIs from Optional to Required.
  • Removed the value OTHER from the osType parameter in the prepare API.
  • Updated the Alipay+ MPP Android SDK as follows:
  • Updated the Alipay+ MPP iOS SDK as follows:

Document improvements

  • Added the Get Started document to guide the MPPs through the integration and acceptance guide. For more information, see Get started with Alipay+ integration.
  • Updated the integration guides of the following payment products:
      • Updated the workflow diagram for making a payment and integration steps.
      • Updated the code identification step to make it clearer and more accurate. Specially:
        • Refined the process flow diagram and its description.
        • Removed the Allowlist solution and Blocklist solution sections, which are deprecated for the Cashier Payment product.
        • Reorganized and improved the How to identify Alipay+ codes chapter.
      • Updated the processing logic of integrating the userInitiatedPay API.
      • In the Bind the user account topic, clarified the integration methods that are available for different terminal types of the MPP client.
      • Updated the workflow diagrams for account binding and unbinding steps.
      • Reorganized the table of contents to make it clearer and easy to find.
      • Removed the topics about providing user information in certain conditions. If you need these topics, contact the Alipay+ Solution Architect.
      • Updated the workflow diagram to better describe the payment workflow.
      • Divided the original Identify the code section into two substeps: Filter the code and Identify the code, to better describe the process.
  • Removed the specification documentation of the inquiryUserInfo and inquiryCustomerId APIs from the Alipay+ Document Center. If you need to implement these APIs to provide user information, contact the Alipay+ Solution Architect.
  • Added an Integration and acceptance chapter to the FAQ.
  • Updated the Reconcile documentation as follows:
    • Added an introduction about Banker's rounding. For more information, see Banker's rounding.
    • Improved the description of the settlementAmountValue parameter and the feeSettlementAmountValue parameter to clarify how they are calculated.

Version 1.1.2

Release date: 2022/10/28

New features

  • Released the documentation that provides guidance for MPPs on how to display Alipay+ brand-related elements on digital user interfaces before, during, and after the payment is processed by Alipay+ Core. For more information, see Brand Display Guidelines for Alipay+ Core MPP Integration.

Document improvements

  • Updated the definition of the following terms: Acquiring Service Provider (ACQP), Mobile Payment Provider (MPP), and Common Business Day. For more information, see Glossary.

Version 1.1.1

Release date: 2022/09/30

New features

  • Added a new domain name (https://open-na.alipayplus.com) for Alipay+ APIs. Now there are two domain names for you to select. For more information, see API reference.

Document improvements

  • Updated the product introduction for Auto Debit and Cashier Payment. Now the product introduction includes a new section, Page detail requirements, which replaces the UX design guidelines provided in the User Experience Guidelines. For more information, see Product Introduction for Auto Debit and Cashier Payment.
  • Updated the integration document of the payment products:
    • Improved the Reconcile section in that:
      • Optimized the Overview topic to include information about some basic concepts about reconciliation.
      • Added a topic Perform reconciliation to introduce a step-to-step guide on how to do reconciliations.
      • Updated the samples and the description of the parameters in each financial report.

For more information, see Reconcile.

    • Replaced the Post payment section with two new sections, Return payment results and Cancel or refund a payment for the integration document of Auto Debit, Cashier Payment, User-presented Mode Payment, and Merchant-presented Mode Payment. The new sections explain the related topics in an optimized method.

Version 1.1.0

Release date: 2022/08/31

New features

  • Upgraded the Alipay+ MPP Client SDK. The new SDK features broader applicability, higher security, and faster response, and is well-documented and open-sourced to MPPs who have signed NDAs with Alipay+. For more information, see Alipay+ MPP Client SDK.
    • Accordingly, the following documents are updated:
    • Meanwhile, Alipay+ continues to maintain the older SDK edition. MPPs that have integrated the older SDK edition are not impacted. For more information, see Alipay+ client SDK integration guide.

Enhanced features

The redirection-back from an MPP app to the merchant WAP page for Cashier Payment is now properly supported, so relevant modifications are made. For details, see Guide on redirections between the merchant and the Mobile Payment Partner and Cashier Payment.

Document improvements

  • Added the FAQ documentation for MPPs, containing frequently asked questions about Alipay+ risk management and partner services. For more information, see FAQ.
  • Removed the inquiryRiskScore API from the API Reference documentation and Auto Debit integration guide.
  • Removed the SDK download addresses from the SDK Reference documentation. You can contact the Alipay+ Solution Architect to obtain SDK packages.
  • Removed the following parameters from the API reference. Note that this change is backward compatible.
    • From the request parameters of the pay API:
      • order.goods.goodsBrand
      • order.merchant.store.storeOperatorId
      • order.merchant.store.storePhoneNo
    • From the response parameters of the pay API:
      • paymentAmount
      • payToAmount
      • order.goods.goodsBrand
      • order.merchant.store.storeOperatorId
      • order.merchant.store.storePhoneNo
      • merchant
      • paymentCurrency
      • Value STORE_CODE of the codeType parameter

Version 1.0.0

Release date: 2022.07.29

Important:

Since 2022/07/29, the Alipay+ Document Center has been restructured to provide you with a better user information experience in the following terms:

  • Centralized content reading: You can select the role and the product that you want to explore to enter a dedicated content domain.
  • Better navigation experience: Horizontal tab navigation plus vertical navigation allows you to find the information more easily and quickly; the aggregated overview page for each tab guides you through the important content that Alipay+ provides to you; quick entry provided for you to arrive at the API and SDK reference in one step.
  • Public technical content information: Since this version, most of the documentation on the Alipay+ Documentation Center has been disclosed to all users except for the following three books:
    • Rules
    • Operation guides
    • Alipay+ Partner Workspace User Guide
  • Standardized version control: Alipay+ supports you in switching the version as you require.
  • Optimized content structure: The content structure of the integration guides is restructured to allow you to find the product introduction, and the content about reconciliation more conveniently. In addition, the product introduction and the integration guides for the Online Payment are also refined to improve the content quality.
  • Useful support information: Find the support information at the footer if you need any help with technical issues or business operations.

Other document improvements

  • Removed the registration and notifyRegistrationStatus APIs from the API Reference (MPP) documentation. If you need to implement the merchant registration capability, contact the Alipay+ Solution Architect.

History for previous updates

Note: Starting from 2022/07/29, the Alipay+ documentation is restructured to support version control. The following list describes important updates to our documentation before this date.

July 15 2022

New features

Released new features to support MPPs in adopting two modes for merchant registration: Reporting Mode and Approval Mode. This leads to the following document updates:

    • Added the REGISTRATION_In_PROCESS result code and the description about when to use it in the More information section.
    • Updated the result message for the SUCCESS result code.

Enhanced features

Changed the merchantInfo.registrationDetail.registrationNo parameter in the registration API from Required to Optional to satisfy the needs of individual merchant registration.

June 30 2022

New features

Released the non-client-SDK integration solution for the Cashier Payment, Auto Debit, and Merchant-presented Mode Payment products. For more information, see the following documents:

Enhanced features

Updated the logic of calculating the following amounts: paymentAmount, payToAmount, and surchargeAmount. For more information, see pay.

Document improvements

  • Updated the API reference documentation, to make it more accurate and clear. This includes:
    • Added more detailed descriptions. For example, for optional request parameters, added conditions when these parameters are specified by Alipay+; for optional response parameters, added conditions when these parameters are required to be returned by the MPP.
    • Refined the Result processing logic section for APIs that are invoked by the MPP.
    • Added the How to return the result section for APIs that are invoked by Alipay+.
    • Adjusted the sequence of some parameters based on their relevance.
    • Fixed several errors in the sample codes.
    • Fixed some grammatical errors to improve readability.

For more information, see API Reference (MPP).

  • Updated the Result codes table as follows:
    • Added the NO_INTERFACE_DEF result code for all APIs.
    • Added the USER_PAYMENT_VERIFICATION_FAILED and MERCHANT_NOT_REGISTERED result codes for the pay API.
    • Added the ORDER_IS_CLOSED result code for the userInitiatedPay API.
    • Added the REPEAT_REQ_INCONSISTENT result code for the refund and prepare APIs.
    • Deleted the INVALID_API result code for all APIs.
    • Deleted the REPEAT_REQ_INCONSISTENT result code for the registration API.
    • Deleted the INVALID_CONTRACT result code for the responseRetrieval API.
  • Updated the Payment result codes table for the notifyPayment and inquiryPayment APIs as follows:
    • Added the following payment result codes:
      • UNAVAILABLE_PAYMENT_METHOD
      • USER_PAYMENT_VERIFICATION_FAILED
      • MERCHANT_NOT_REGISTERED
  • Deleted the following 21 response parameters in the registration API while maintaining backward compatibility:
    • merchantInfo.registrationDetail.attachments.attachmentType
    • merchantInfo.registrationDetail.attachments.file
    • merchantInfo.registrationDetail.attachments.attachmentName
    • merchantInfo.registrationDetail.attachments.content
    • merchantInfo.registrationDetail.attachments.contentType
    • merchantInfo.registrationDetail.contactInfo.contactNo
    • merchantInfo.registrationDetail.contactInfo.contactType
    • merchantInfo.registrationDetail.registrationEffectiveDate
    • merchantInfo.registrationDetail.registrationExpireDate
      merchantInfo.merchantAddress.region
    • merchantInfo.merchantAddress.state
    • merchantInfo.merchantAddress.city
    • merchantInfo.merchantAddress.address1
    • merchantInfo.merchantAddress.address2
    • merchantInfo.merchantAddress.zipCode
    • merchantInfo.logo.logoName
    • merchantInfo.logo.logoUrl
    • storeInfo.storeContacts.fullName
    • storeInfo.storeContacts.identificationId
    • storeInfo.storeContacts.contactNo
    • storeInfo.feeTier
  • Released the documentation for Alipay+ Center that contains an introduction and integration solutions for MPPs. For more information, see Alipay+ Center.
  • Updated the brand display guidelines. This includes the following documents:
  • Changed a condition of cancelling the payment in all the integration documents for MPPs. For more information, see Cancel the transaction section in each integration guide for MPPs.

May 27 2022

Enhanced features

Added an entry to download the Alipay+ logo asset in Alipay+ foundational brand guidelines and UX design guidelines for Mobile Payment Partners.

Document improvements

  • Deleted the scopes parameter from the idempotency fields table as it can not be used to control the idempotency for the prepare API.

April 29 2022

Document improvements

  • Changed the accuracy of the Request-Time and Response-Time header fields from milliseconds to seconds.
  • Added the retry mechanism of the inquiryPayment, cancelPayment, and refund APIs in the integration guides.
  • Changed the refund time window from 365 days to 366 days.
  • Updated the values of the scopes parameter in the prepare API.

March 31 2022

New features

Open sourced the Alipay+ Server SDK to MPPs who have signed NDAs with Alipay+.

Added a glossary of terms that are used in Alipay+ for your convenience. For more information, see Glossary.

Fixed bugs

Fixed the spelling of the following parameters in the Transaction Detail Report and Fee Report:

  • Updated orignalTransactionRequestId to originalTransactionRequestId.
  • Updated feeSettleAmountValue to feeSettlementAmountValue.