Quick Start: QR Payment API Integration

This guide provides a quick overview of integrating the QR payment APIs to enable both Merchant-Presented Mode (MPM) and Customer-Presented Mode (CPM) transactions, along with essential post-payment operations like querying, refunding, and voiding transactions.

I. Introduction to QR Payments

QR code payments offer a convenient way for merchants to accept payments, primarily through two modes:

  • Merchant-Presented Mode (MPM): The merchant generates and displays a QR code, which the customer scans using their mobile wallet to complete the payment.

  • Customer-Presented Mode (CPM) / Quick Pay: The customer generates a QR code on their mobile wallet app and presents it to the merchant for scanning to initiate the payment.

II. Prerequisites

Before you begin, ensure you have:

  • API Client/SDK: Install a suitable API library for your programming language (e.g., Java SDK).

  • Authentication Credentials: Obtain your CLIENT_ID, merchantPrivateKey, and alipayPublicKey (or equivalent keys/IDs from your payment service provider) to initialize the API client.

III. Payment Initiation Flows

A. Merchant Presented Mode (MPM): Generate QR Code (Customer Scan)

This flow is suitable when the merchant displays a QR code for the customer to scan (generate-qr-code-customer-scan).

Steps:

1

Initiate Payment Request (Server-side):

  • Your merchant system submits an order payment request including details like paymentRequestId (unique ID from merchant), paymentAmount (currency and value), order information, productCode (e.g., CASHIER_PAYMENT), paymentNotifyUrl, and paymentRedirectUrl.

  • Call the generate-qr-code-customer-scan API (or pay API) with these parameters.

2

Receive Payment Response (Server-side):

The API returns a response containing the QR code data, often as a normalUrl or codeValue. This URL typically leads to a checkout page or an image of the QR code.

3

Display QR Code (Client-side):

Pass the normalUrl or codeValue to your client-side application. The merchant system displays the generated QR code to the customer.

4

Customer Scans and Pays:

The customer uses their mobile wallet app to scan the displayed QR code and authorize the payment.

5

Receive Payment Result Notification (Server-side):

Antom (or the payment service) sends an asynchronous notification (notifyPayment) to your specified paymentNotifyUrl once the payment is completed or fails. This notification contains the paymentRequestId, paymentId, paymentAmount, and result status (e.g., SUCCESS, FAIL, PROCESSING). You should verify the notification's signature.

6

Display Payment Results (Client-side):

After the payment, the customer might be redirected to your paymentRedirectUrl to show transaction results. Note that client redirection alone should not be the sole basis for determining payment success.

B. Customer Presented Mode (CPM): Quick Pay (Merchant Scan)

This flow is used when the customer presents a QR code for the merchant to scan (quick-pay-merchant-scan).

Steps:

1

Customer Presents QR Code:

The customer generates and presents a QR code (often referred to as a "payment code" or "barcode") via their mobile wallet app.

2

Merchant Scans QR Code:

The merchant's POS system or reader scans the customer's presented QR code. This scan typically obtains a customer payment token (e.g., authCode).

3

Submit Payment Request (Server-side):

  • Your merchant system submits a payment request to the API, including the paymentRequestId, paymentAmount, order information, and the authCode obtained from scanning the customer's QR code.

  • Call the quick-pay-merchant-scan API with these details.

4

Receive Payment Result Notification (Server-side):

The payment service processes the request and sends an asynchronous notification (notifyPayment) to your specified paymentNotifyUrl with the paymentId and ultimate transaction result.

5

Confirm Payment (Merchant-side):

Update the order status in your system based on the notification. Confirm the payment to the customer.

IV. Post-Payment Operations

A. Query Transaction Status (query-transaction-status)

To check the status of a specific transaction:

  1. Create Query Request (Server-side):

    • Initiate a query request using the merchant's paymentRequestId or the paymentId received from the payment system.

  2. Retrieve Response:

    • The response will contain the paymentStatus (e.g., SUCCESS, FAIL, PROCESSING) and other transaction details.

  3. Best Practice: It is recommended to perform a round-robin query at intervals (e.g., every 2 seconds) until a final status (SUCCESS/FAIL) or an asynchronous notification is received.

B. Refund (refund)

To issue a refund for a successful transaction:

  1. Initiate Refund Request:

    • Send a refund request including the paymentId of the original transaction, the refundAmount, and a refundRequestId.

    • Call the refund API.

  2. Process Refund Response:

    • Handle the response, which will indicate whether the refund was initiated successfully.

    • (Optional) You can query refund progress using a refund inquiry API if the refund is not immediate.

C. Void (void)

To cancel a pending payment or pre-authorized transaction before settlement:

  1. Initiate Void Request:

    • Send a void request, typically using the paymentRequestId or paymentId of the transaction you wish to cancel.

    • Call the void API.

  2. Process Void Response:

    • The response confirms if the void operation was successful.

D. Close Order (close-order)

To explicitly close an order, often when a payment has timed out or is no longer expected to be completed:

  1. Initiate Close Order Request:

    • Send a request to close the order, using the paymentRequestId or a similar order identifier.

    • Call the close-order API.

  2. Process Close Order Response:

    • The response confirms the order has been marked as closed on the payment system's side.

Last updated