> For the complete documentation index, see [llms.txt](https://smartpossdk.gitbook.io/paywizard-open-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration.md).

# 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` 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:**

{% stepper %}
{% step %}
**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.
  {% endstep %}

{% step %}
**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.
{% endstep %}

{% step %}
**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.
{% endstep %}

{% step %}
**Customer Scans and Pays**:

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

{% step %}
**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.
{% endstep %}

{% step %}
**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.
{% endstep %}
{% endstepper %}

### **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:**

{% stepper %}
{% step %}

### **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.
{% endstep %}

{% step %}

### **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`).
{% endstep %}

{% step %}

### **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.
  {% endstep %}

{% step %}

### **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`.
{% endstep %}

{% step %}

### **Confirm Payment (Merchant-side)**:

Update the order status in your system based on the notification. Confirm the payment to the customer.
{% endstep %}
{% endstepper %}

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.