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
, andalipayPublicKey
(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:
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
, andpaymentRedirectUrl
.Call the
generate-qr-code-customer-scan
API (orpay
API) with these parameters.
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.
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.
Customer Scans and Pays:
The customer uses their mobile wallet app to scan the displayed QR code and authorize the payment.
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.
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:
IV. Post-Payment Operations
A. Query Transaction Status (query-transaction-status
)
query-transaction-status
)To check the status of a specific transaction:
Create Query Request (Server-side):
Initiate a query request using the merchant's
paymentRequestId
or thepaymentId
received from the payment system.
Retrieve Response:
The response will contain the
paymentStatus
(e.g.,SUCCESS
,FAIL
,PROCESSING
) and other transaction details.
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
)
refund
)To issue a refund for a successful transaction:
Initiate Refund Request:
Send a refund request including the
paymentId
of the original transaction, therefundAmount
, and arefundRequestId
.Call the
refund
API.
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
)
void
)To cancel a pending payment or pre-authorized transaction before settlement:
Initiate Void Request:
Send a void request, typically using the
paymentRequestId
orpaymentId
of the transaction you wish to cancel.Call the
void
API.
Process Void Response:
The response confirms if the void operation was successful.
D. Close Order (close-order
)
close-order
)To explicitly close an order, often when a payment has timed out or is no longer expected to be completed:
Initiate Close Order Request:
Send a request to close the order, using the
paymentRequestId
or a similar order identifier.Call the
close-order
API.
Process Close Order Response:
The response confirms the order has been marked as closed on the payment system's side.
Last updated