This guide describes how to integrate the Alipay+ NFC product into your system.

Before you begin

Before you learn more about how to integrate with the Alipay+ NFC service, ensure that you are familiar with the following things:

• The Alipay+ NFC provided user experience.
• The configuration requirements in the Quick Start section of the SDK reference.

Build an integration

To integrate the Alipay+ NFC product, use the provided APIs and SDKs to complete the following tasks:

Initiate SDK

The SDK must be in connected status to perform all the actions listed below.

Make sure to:

• Call the init() API and the connect() API after the user logs in.
• Call the disconnect() API when the user logs out.

For more details, see Initiate SDK.

Proxy SDK requests

You must proxy all requests from the Alipay+ NFC SDK to Mastercard and the Ant server through your MPP app and server. This is handled by the NFCRequestProxy SPI. For more information about how this process works and what you need to do, see Proxy SDK requests.

Open Alipay+ NFC pages

When a user opens the Alipay+ NFC page in your app, you must display a different page based on the user's token status. For more information, see Open Alipay+ NFC pages.

Activate card tokens

Users must activate the tokenization process to use the Alipay+ NFC payment service. You can implement two methods for token activation:

Manual activation (mandatory)

Manual activation is a user-initiated process that starts after the user applies for the Alipay+ NFC service. You must implement manual activation as a fallback in case silent activation fails. For more details, see Manual activation.

Note: The tokenization process takes 20-30 second. It’s recommended to display a progress bar to keep the user informed.

Silent activation (recommended)

To improve the user experience, it is highly recommended to integrate silent activation. This method streamlines the 20-30 second tokenization process. You can initiate silent activation when the user logs into your app or opens the Alipay+ NFC page. For more details, see Silent activation.

Replenish

The Alipay+ NFC SDK requires a new set of payment credentials for each transaction. The SDK fetches and stores these credentials from Mastercard.

• Automatic replenishment: After each transaction, the SDK checks the number of available credentials. If the count falls below a set threshold (default is 10), the SDK automatically requests new credentials. For more information, see Auto-replenish.
• Manual replenishment: You can also manually trigger replenishment by calling the replenish() API. For more information, see Manual-replenish.

Manage card tokens

After a card token is activated, a user can suspend or reactivate the service. Both actions require a network connection. Alipay+ manages the token status on both the server and the SDK.

• To suspend the service, call the lock() API.
• To reactivate the service, call the unlock() API.

For more details, see Manage the token.

Make a payment

To enable payments, integrate the payment-related APIs. For details, see Make a payment.

Convert authorization to pay

Alipay+ converts the regular authorization, authorization reversal, clearing, and authorization expiry of Mastercard into payment and refund requests. For more information about how this conversion works, see Convert authorization to pay.

Return payment results

You can synchronously return the payment result to Alipay+ in the response to the pay API request. However, to ensure that Alipay+ can receive the payment result, you need to integrate the inquiryPayment API. It is also recommended to integrate the notifyPayment API. For more information about how to integrate the APIs, see Notify payment result and Respond to payment inquiry.

Cancel and refund

To allow users to cancel or refund payments, integrate the refund and cancelPayment APIs. For more information about how to integrate the APIs, see Cancel a payment and Refund.

Refund for the excess refund and unlinked refund

The Alipay+ NFC service also supports excess refunds and unlinked refunds. For more information about how to refund the excess amount and unlinked refund, see Refund for the excess refund and unlinked refund.

More information

Go through the section below to obtain more information that empowers your integration:

• When using APIs to integrate, you need to take the following things into consideration:

• Make a POST request to the corresponding address with the identity information, signature, and business parameters in the HTTP request. For more information about the structure of a request and response, see API overview.
• To ensure message transmission security, you must sign the request and validate the signature properly. When calling an Alipay+ API, you must sign the API request and validate the response signature accordingly; when receiving an API call from Alipay+, you must validate the request signature and sign the API response accordingly.

• For the full list of APIs and SDKs that are provided for User-presented Mode Payment, see APIs and SDKs.