Alipay+ DocsAlipay+ Docs

Release Notes

Version 1.3.5

Release date: 2024/02/29

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.
  • Corrected the description of the SDK method to consult the Alipay+ payment method information in the Cashier Payment and Auto Debit integration guides.
  • Added an FAQ about how to troubleshoot an invalid signature issue.
  • Added an FAQ specifying the usage of the API endpoint in both the production and sandbox environments. For more information, see Integration.
  • Added an FAQ about the refund scenario when a merchant's account has insufficient funds. For more information, see Migration from AlipayCN or AMS.

Version 1.3.4

Release date: 2023/12/29

Document improvements

Version 1.3.3

Release date: 2023/10/31

Enhanced features

  • 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

  • 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.
  • Added the information that Alipay+ does not retry to send the notification if you test Alipay+ APIs in the sandbox environment. For more information, see Retry mechanism.
  • Removed the incorrect description from the refund API specification that partial refunds are not allowed for IDR.

Version 1.3.2

Release date: 2023/08/31

Enhanced features

Document improvements

  • Corrected the regular expression of an Alipay+ 19-digit code to /^289\d{10}6\d{5}$/, which is used in the payment code identification for payment routing in the User-presented Mode Payment scenario. See Routing logic for details.
  • Added a condition under which the env.osType parameter must be specified when the ACQP calls the pay (Merchant-presented Mode Payment -Entry Code) API.
  • Removed the value U from the value list of the paymentResult.resultStatus parameter in the notifyPayment API.

Version 1.3.1

Release date: 2023/06/30

Document improvements

  • Updated the page designs that are supported by the MPP in the User-presented Mode Payment scenario. For more information, see the User experience section of User-presented Mode Payment production introduction.
  • Updated the page designs that are supported by the MPP in the Merchant-presented Mode Payment scenario. For more information, see the User experience section of Merchant-presented Mode Payment production introduction.
  • Refined the content structure of the Migration guide for AlipayCN to Alipay+ to make it easy to use.
  • Corrected the field name feeSettleAmountValue to feeSettlementAmountValue in the sample fee reports of the Fee Report topic.

Version 1.3.0

Release date: 2023/04/28

New features

  • Added the USER_NOT_EXIST result code for the refund API.

Enhanced features

  • Updated the types of Alipay+ payment codes used in the User-presented Mode Payment scenario. For more information, see Code types and rules.

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+.

Version 1.2.6

Release date: 2023/02/28

Enhanced features

  • Modified the maximum length of the following parameters from 64 characters to 32 characters:
  • Shortened the minimum waiting time for updating an existing registration from 7 natural days to 30 minutes since the last registration request, and removed the prohibition on updating an existing registration that is not processed. For more information, see the registration API specification.
  • Updated the design of the Alipay+ Checkout Page in the Cashier Payment - Web scenario. For more information, see the User experience section of Cashier Payment production introduction.
  • Updated the User Agent string that is used to identify the KaKao Pay wallet in the Merchant-presented Mode Payment Entry Code scenario. For more information, see Identify the wallet and route the payment and mapping table.

Document improvements

  • Updated the description of the authClientId parameter in the cancelToken and authNotify API specifications, stating that the value of the authClientId parameter must be consistent with the one in the prepare API.
  • Added a note to emphasize that the paymentNotifyUrl parameter in the pay APIs must be an HTTPS URL. For more information, see the following API specifications:
  • Added a note to emphasize that the paymentRedirectUrl parameter in the pay APIs must be an HTTPS URL or in the form of a URL scheme. For more information, see the following API specifications:
  • Corrected the name of the logging API provided by Alipay+ iOS SDK from log to logWithName in the iOS SDK reference. For more information, see iOS SDK Overview.
  • Added a note in the Reconcile documentation to emphasize that Alipay+ reports prevail when discrepancies exist due to payment status inconsistencies between the ACQP system and the Alipay+ system. For more information, see Process overview of the Perform reconciliation topic.

Version 1.2.5

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

  • Added a note that the ACQP needs to ensure that the amounts in IDR are not in cents. For more information, see the note added to the paymentAmount.value, refundAmount.value, and transactionReceipt.orderAmount.value parameters in the API reference documentation.
  • Removed the value OTHER from the osType parameter in the prepare API.
  • Removed the enumeration value MINI_APP from the terminalType parameter in the prepare API specification because currently authorization cannot be initiated via mini apps.
  • The value of the authClientId parameter in the applyToken API must be the same as the one specified in the prepare API.
  • Defined the maximum length of the declarationRequestsNotFound parameter as 64 characters in the inquireDeclarationRequests API.

Document improvements

  • Released a series of video tutorials on Alipay+ integration and partner services to enrich your information experience. To watch these videos, see Videos.
  • Added a quick start for Cashier Payment to help the ACQPs quickly build a smooth Cashier Payment process with the Alipay+ Unified Payment solution. For more information, see Quick start.
  • Added an introduction about the Alipay+ customs declaration product. For more information, see Customs Declaration.
  • Removed the Older Edition documentation. Instead, the Older Edition documentation is released as Version 1.0.5.
  • Removed the MPP brand name table in Brand Display Guidelines for Cashier Payment. For the latest MPP brand names, see the topic Brand names of Mobile Payment Providers.
  • Reorganized the information architecture of SDK reference documentation to make it easy to use.
  • Updated the integration guide for User-presented Mode Payment as follows: Removed the Mapping between MPP and routing number table in the original Alipay+ payment codes chapter, and changed the chapter name to Code rules and types.
  • 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.2.4

Release date: 2022/10/28

New features

Added the mppPaymentId parameter in the following API specifications:

Enhanced features

    • Removed the option to display the standalone Alipay+ logo on the merchant's cashier page. Now an aggregated acceptance mark is required.
    • Added a new Acceptance mark generator that can be used to generate Alipay+ aggregated acceptance marks.

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.
  • Added a note to clarify the different acquirerId used when constructing the CDN URL for consulting payment method information in the production and sandbox environment. For more information, see Cashier Payment and Auto Debit integration guides.
  • Improved the description about the redirection from the MPP side to the ACQP side in the Cashier Payment scenario. For more information, see Cashier Payment integration guide and the description of the paymentRedirectUrl parameter in the pay(Cashier Payment) API specification.
  • Added a note to the applyToken API specification that specifies the effective period of long-term access tokens must be at least 10 years.
  • Added the image size of the QR code that is returned by Alipay+ in the Merchant-presented Mode Payment scenario. For more information, see the description of the displayType parameter in the pay (Merchant-presented Mode Payment - Order Code) API specification.
  • Added a chapter to guide the ACQP to go through tasks before, during, and after UAT. For more information, see UAT checklist.
  • Added the rejectionReason parameter to the notifyRegistrationStatus API specification.

Version 1.2.3

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

  • Released the MPP capabilities document to introduce the different capabilities supported by various MPPs.
  • Updated the Upgrade from Cashier Payment tile mode document to introduce how to display the Alipay+ unified payment method along with other Alipay+ payment methods in a list.
  • Updated the description of the order.merchant.merchantAddress parameter to include the following content: The value of this parameter is used by Alipay+ to determine whether the transaction is domestic or cross-border and therefore affects the fee calculation logic.
  • Changed the paymentNotifyUrl parameter in the pay (Auto Debit) and pay (User-presented Mode Payment) APIs from Required to Optional.
  • Changed the maximum length of the merchant.merchantMCC and store.storeMCC parameters from 32 to 4 in the following pay API specifications:
    • pay (Cashier Payment)
    • pay (Auto Debit)
    • pay (User-presented Mode Payment)
    • pay (Merchant-presented Mode Payment - Entry Code)
    • pay (Merchant-presented Mode Payment - Order Code)
    • userInitiatedPay
  • Changed the settlementStrategy.settlementCurrency parameter from Optional to Required in the following API specifications:
    • pay (Cashier Payment)
    • pay (Auto Debit)
    • pay (User-presented Mode Payment)
    • pay (Merchant-presented Mode Payment - Entry Code)
    • pay (Merchant-presented Mode Payment - Order Code)
    • userInitiatedPay
  • Updated the integration guides of the following payment products:
      • For the entry code scenario, clarified the payment routing logic and updated the mapping between MPPs and their UA strings.
      • For the order code and private order code scenarios, refined the workflow diagrams and integration steps.
      • Added the Alipay+ Payment Codes chapter to better explain the routing logic in Accept a payment.
      • Updated the workflow diagrams and processing logic of integrating the pay API.

Version 1.2.2

Release date: 2022/08/31

New features

  • Added support for Cashier Payment with mini programs. You can now accept a payment with a merchant mini program that is deployed in the mobile apps of Alipay+'s MPPs. For the step-by-step guide for integration and the differences when accepting payments with mini-programs in comparison with other merchant platforms (App, Web, or WAP), see Accept payments with Mini Program.
  • Added support for CDN-based consultation methods in the sandbox environment. For the CDN URL formats used in the sandbox environment, see Cashier Payment and Auto Debit integration guides.

Enhanced features

  • Added a requirement on how to use the registration API in TSP mode: For each merchant, the ACQP needs to provide each TSP with a unique value of the merchantInfo.referenceMerchantId parameter. For more information, see any of the following documents:

Document improvements

  • Removed the SDK download addresses from the SDK reference documentation. You can log on to Alipay+ Developer Center to download 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 for User-presented Mode Payment, Merchant-presented Mode Payment, Cashier Payment, and Auto Debit:
      • paymentMethod.customerId
      • order.goods.goodsBrand
      • order.merchant.store.storeOperatorId
      • order.merchant.store.storePhoneNo
      • order.goods.goodsBrand
      • order.merchant.store.storeOperatorId
      • order.merchant.store.storePhoneNo
    • From the response parameters of the prepare API:
      • acquirerId
      • pspId
  • Added a Notes on result code section in the API reference documentation for all the pay APIs to explain the logic of the ORDER_IS_CLOSED result code.
  • Released the following documents to provide guidance on migration to the Alipay+ Unified Payment solutions:
  • Updated frequently asked questions about Alipay+ risk management, integration and acceptance, and partner services. For more information, see FAQ.

Version 1.2.1

Release date: 2022/08/05

New features

  • Updated the CDN URL formats for CDN-based consultation methods in the Cashier Payment and Auto Debit integration guides.
  • Updated the Android SDK and iOS SDK packages for CDN-based consultation methods in Android and iOS integration guides.
  • Removed the allowedPspRegions parameter from the specification of the pay (Cashier Payment) API.
  • Updated the valid values of the walletForAccountBinding.walletName parameter in the specifications of the applyToken and authNotify APIs.

Enhanced features

Added the registrationResult.rejectionReason parameter to the inquiryRegistrationStatus and notifyRegistrationStatus APIs.

Document improvements

  • Improved the description of the registrationNo parameter in the registration API.

Version 1.2.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 and merchant registration 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.

New features

    • The following parameter changes are applied to the Alipay+ Unified Payment edition of Auto Debit:
      • In the pay (Auto Debit) API specification, the paymentFactor.presentmentMode parameter is changed to Required and must be set to UNIFIED.
      • In the prepare API specification,
        • added the following request parameters: paymentAmount, settlementStrategy, userRegion, and boundWalletNames.
        • removed the following response parameters: schemeUrl, applinkUrl, and appIdentifier.
      • In the applyToken API specification, removed the customerBelongsTo request parameter and added the walletForAccountBinding response parameter.
      • In the authNotify API specification, added the walletForAccountBinding request parameter.
  • Released two CDN-based methods for consulting the Alipay+ payment method information in Cashier Payment and Auto Debit scenarios. The new methods enable the ACQP/merchant to directly request JSON data or logo assets from the Alipay+ CDN server with the following benefits:
    • less integration cost, higher response speed, and better information transparency
    • streamlined integration experience and better real-time performance

For more information, see the topic How to consult the payment method information in the Cashier Payment and Auto Debit integration guides.

Note:

Alipay+ continues to maintain the consultPayment API to provide service consistency. ACQPs that have integrated the consultPayment API are not impacted. For how to consult Alipay+ payment method information by using the consultPayment API, see consultPayment integration.

  • Added the settlement message function for ACQPs. For how to enable this function to receive a message that is attached to each Alipay+ settlement, see Receive settlement message in the Reconcile section.

Other document improvements

Version 1.1.0

Release date: 2022/04/15

This version covers the updates since 2022/04/15, which mainly include the following important additions and improvements:

  • Released the Alipay+ Unified Payment edition of Cashier Payment. In this version, Alipay+ supports consulting the payment method information via the consultPayment API or the Alipay+ ACQP Client SDK. Since 2022/05/27, Alipay+ has supported the aggregated logo feature.
  • Added the support of the TSP integration mode for ACQPs.
  • Improve the API reference documentation in terms of the parameter descriptions, result codes, and so on.
  • Optimized the documentation of Reconciliation in terms of adding a guide about how to perform reconciliation, refining the parameter description and sample codes, and so on.
  • Added the documentation for support of BNPL channels.
  • Added the FAQ documentation for ACQPs.

For more information about all the updates in Version 1.1.0, see the change history below.

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

Enhanced features

  • Changed the merchantInfo.registrationDetail.registrationNo parameter in the registration API from Required to Optional to satisfy the needs of individual merchant registration.
  • Added the following 6 valid values to the pspRegistrationResultList.pspName parameter in the inquiryRegistrationStatus and notifyRegistrationStatus APIs to keep consistent with the newly-launched feature for merchant registration at MPP's side:
    • BPI
    • RABBIT_LINE_PAY
    • BOOST
    • NaverPay
    • KLARNA
    • TINABA

Document improvements

  • Improved the Reconcile section in that:
    • Optimized the Overview topic to include information about some basic concepts about the 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.
    • Added a subsection Explore more to introduce miscellaneous information, for example, how to select the reconciliation mode, and how to handle exceptional cases.
  • Removed the following 25 request parameters from the specification of the registration API. Note that this change is backward compatible.
    • merchantInfo.logo.logoName
    • merchantInfo.logo.logoUrl
    • merchantInfo.merchantAddress.region
    • merchantInfo.merchantAddress.state
    • merchantInfo.merchantAddress.city
    • merchantInfo.merchantAddress.address1
    • merchantInfo.merchantAddress.address2
    • merchantInfo.merchantAddress.zipCode
    • merchantInfo.representativeName
    • merchantInfo.representativeId
    • 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.shareholderName
    • merchantInfo.shareholderId
    • storeInfo.feeTier
    • storeInfo.storeContacts.fullName
    • storeInfo.storeContacts.identificationId
    • storeInfo.storeContacts.contactNo

June 30 2022

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 recommended to be specified by the ACQP; for optional response parameters, added conditions when these parameters are returned by Alipay+.
    • Refined the Result processing logic section for APIs that are invoked by the ACQP.
    • 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 (ACQP).

  • Updated the Result codes table as follows:
    • Added the NO_INTERFACE_DEF result code for all APIs.
    • Added the PAYMENT_AMOUNT_INVALID result code for the following APIs:
      • pay (Auto Debit)
      • pay (User-presented Mode Payment)
      • pay (Merchant-presented Mode Payment - Entry Code)
      • pay (Merchant-presented Mode Payment - Order Code)
      • pay (Cashier Payment)
      • userInitiatedPay
    • Added the ORDER_IS_CLOSED result code for the userInitiatedPay API.
    • Added the CURRENCY_NOT_SUPPORT result code for the refund API.
    • Deleted the INVALID_API result code for all APIs.
    • Deleted the EXPIRED_CODE result code for the following APIs:
      • pay (Merchant-presented Mode Payment - Entry Code)
      • pay (Merchant-presented Mode Payment - Order Code)
      • pay (Cashier Payment)
    • Deleted the INVALID_CODE result code for the following APIs:
      • pay (Merchant-presented Mode Payment - Entry Code)
      • pay (Merchant-presented Mode Payment - Order Code)
      • pay (Cashier Payment)
    • Deleted the REPEAT_REQ_INCONSISTENT result code for the registration API.
    • Deleted the REGISTRATION_STATUS_ABNORMAL result code for the notifyRegistrationStatus API.
  • Updated the brand display guidelines. This includes the following documents:
  • Changed the term Legacy Documentation to Older Edition, because the Tile and Bundle Mode of Cashier Payment is still available for some clients, and its documentation is still maintained. For more information, see Older Edition.

May 27 2022

New features

  • Released the aggregated logo feature for Cashier Payment (Alipay+ Unified Payment). For more information, see UX design guideline and Product introduction.
  • Released the TSP integration mode for ACQPs. In this mode, ACQPs can integrate Alipay+ products by cooperating with their TSPs. For more information, see the following three documents:

Enhanced features

Document improvements

  • Deleted the appIdentifier parameter in the pay (cashier payment) API.
  • Added the enumeration values of the paymentOptions.promoNames parameter in the consultPayment API to include the usable languages for the promotion names.
  • Added a parameter pspId to the response parameters in the pay (cashier payment) API.
  • Changed the report names in the Reconcile section of all the integration documents to match the names in the Alipay+ Rules. Specifically:
    • Clearing Transaction Report is changed to Transaction Detail Report.
    • Clearing Summary Report is changed to Transaction Summary Report.
    • Clearing Fee Report is changed to Fee Report.
  • 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

New features

Enhanced features

Document improvements

  • Updated the notification retry period from "up to 24 hours" to "up to 24 hours 22 minutes" for the notifyPayment API.
  • Changed the accuracy of the Request-Time and Response-Time header fields from milliseconds to seconds.
  • Changed the conditionality of the following parameters from Required to Optional for the consultPayment API:
    • merchant.merchantMCC
    • merchant.merchantName
    • merchant.merchantAddress

April 15 2022

New features

  • Released the Alipay+ Unified Payment edition of Cashier Payment. For more information, see Product introduction.
  • Released the Alipay+ ACQP Client SDK. For more information, see SDK Reference.
  • Added older edition documentation for Cashier Payment tile and bundle mode. For more information, see Older Edition.

Enhanced features

  • Upgraded the pay and consultPayment APIs for the Alipay+ Unified Payment edition of Cashier Payment.

March 31 2022

New features

  • 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 Clearing Transaction Report and Clearing Fee Report:
    • Updated orignalTransactionRequestId to originalTransactionRequestId.
    • Updated feeSettleAmountValue to feeSettlementAmountValue.