---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/InPersonPayments/offlineQRCodePayment/index.md
description: >-
  The offline QR code payment solution enables communication between SaaS cash
  registers and POS devices through cloud services for payments, queries, and
  refunds. Using REST API methods, it supports mobile payment tools such as
  Alipay and WeChat. Key APIs include order creation, transaction query, refund
  application, and refund query. Suitable for retail scenarios, QR code validity
  can be customized, with a recommended setting of 5 minutes to optimize user
  experience.
---
# Offline QR Code Payment

## Main Participants

PingPongCheckout's offline QR code payment solution enables communication between SaaS cash registers and POS devices through cloud services to complete payment, query, and refund transactions. This solution uses REST API methods to generate QR codes for consumers to complete payments using mobile payment tools.

- SaaS Cash Register: Initiates transaction requests, displays QR codes, receives transaction results
- PingPong Acquiring Service: Processes requests, generates QR codes, notifies transaction results
- Consumer Mobile Device: Scans QR code to complete payment

## API List

1. <a href="/en/notes/api/services/InPersonPayments/unifiedPay/" target="_blank">Order Creation API</a>
2. <a href="/en/notes/api/services/InPersonPayments/paymentQuery/" target="_blank">Single Transaction Query API</a>
3. <a href="/en/notes/api/services/InPersonPayments/refund/" target="_blank">Refund Application API</a>
4. <a href="/en/notes/api/services/InPersonPayments/refundQuery/" target="_blank">Refund Query API</a>

## Payment Process

```mermaid
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#E3F2FD',
    'primaryTextColor': '#0D47A1',
    'primaryBorderColor': '#1976D2',
    'lineColor': '#1565C0',
    'secondaryColor': '#BBDEFB',
    'tertiaryColor': '#90CAF9',
    'background': '#F8FBFF',
    'mainBkg': '#E3F2FD',
    'secondBkg': '#BBDEFB',
    'tertiaryBkg': '#90CAF9',
    'actorBkg': '#2196F3',
    'actorBorder': '#1976D2',
    'actorTextColor': '#FFFFFF',
    'actorLineColor': '#1565C0',
    'signalColor': '#0D47A1',
    'signalTextColor': '#0D47A1',
    'c0': '#E8F4FD',
    'c1': '#D1E7DD',
    'c2': '#B3D9FF',
    'c3': '#81C784',
    'noteBkgColor': '#E1F5FE',
    'noteTextColor': '#01579B',
    'noteBorderColor': '#0288D1',
    'loopTextColor': '#0D47A1',
    'activationBkgColor': '#B3E5FC',
    'activationBorderColor': '#0277BD'
  }
}}%%

sequenceDiagram
    participant SAAS as 💳 SaaS Cash Register
    participant PP as 🔄 PingPong Acquiring Service
    participant Consumer as 📱 Consumer Mobile Device

    Note over SAAS,Consumer: 🧾 QR Code Payment Process

    Note over SAAS, PP: 📋 Request Parameters:• cashierDeviceId• paymentMethod=QR Code Payment Method• timeExpire (QR Code Validity Period)

    SAAS->>+PP: 1. Order Creation and Payment Request (unifiedPay)
    
    PP->>PP: 2. Verify Request Signature and Parameters
    
    Note over PP,Consumer: ✅ QR Code Response:• qrCode, qrUrl, qrCodeExpired• status=PROCESSING
    
    PP-->>-SAAS: 3. Return QR Code Information

    SAAS->>Consumer: 4. Display QR Code to Consumer

    Consumer->>Consumer: 5. Scan QR Code

    Consumer->>Consumer: 6. Confirm Payment

    Consumer->>PP: 7. Payment Processing

    opt 🔁 [Poll Order Status - Until Final State]
        Note over SAAS, PP: 🔎 Query Parameters:• transactionId or merchantTransactionId
        
        SAAS->>+PP: 8. Order Result Query (query)
        
        PP->>PP: 9. Query Order Status
        
        Note over PP,Consumer: 📊 Order Status Response:• status=PROCESSING/SUCCESS/FAILED
        
        PP-->>-SAAS: 10. 🔟 Return Order Status Information
    end

    Note over SAAS,Consumer: 🎉 QR Code Payment Completed
```

### Initiate Payment Request
The SaaS cash register sends a unified order payment request (unifiedPay) to the PingPong acquiring service
The request must contain the `cashierDeviceId` parameter to identify the cash register itself
Specify the `paymentMethod` parameter as the corresponding QR code payment method

::: note Note
The `timeExpire` parameter in the request indicates the QR code validity period, which can be set from 1 minute to 3 days. If not set, the default is 3 days.
To improve user experience, it is recommended to set a reasonable QR code timeout, typically 5 minutes for retail scenarios.
:::

### Generate QR Code
The PingPong acquiring service receives the request and verifies the signature
Generates the payment QR code, returns `qrCode` and `qrUrl` parameters
Also returns the `qrCodeExpired` parameter indicating the QR code expiration time

### Display QR Code
The SaaS cash register receives the response and displays the QR code to the consumer
The consumer uses mobile payment tools (such as Alipay, WeChat, etc.) to scan the QR code to complete the payment

### Payment Result Query
The initial response status is usually `PROCESSING`
The SaaS cash register needs to poll the order status through the query API (query)
Or wait for the PingPong acquiring service to push payment results via `notificationUrl`

::: warning Important Notice
The initial status returned by the acquiring service is `PROCESSING`, which only indicates that the QR code generation was successful, not that the payment was completed.
The SaaS cash register should implement a polling mechanism, with a suggested interval of 3-5 seconds per query, until the final payment result is obtained.
:::

## Refund Process

```mermaid
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#E3F2FD',
    'primaryTextColor': '#0D47A1',
    'primaryBorderColor': '#1976D2',
    'lineColor': '#1565C0',
    'secondaryColor': '#BBDEFB',
    'tertiaryColor': '#90CAF9',
    'background': '#F8FBFF',
    'mainBkg': '#E3F2FD',
    'secondBkg': '#BBDEFB',
    'tertiaryBkg': '#90CAF9',
    'actorBkg': '#2196F3',
    'actorBorder': '#1976D2',
    'actorTextColor': '#FFFFFF',
    'actorLineColor': '#1565C0',
    'signalColor': '#0D47A1',
    'signalTextColor': '#0D47A1',
    'c0': '#E8F4FD',
    'c1': '#D1E7DD',
    'c2': '#B3D9FF',
    'c3': '#81C784',
    'noteBkgColor': '#E1F5FE',
    'noteTextColor': '#01579B',
    'noteBorderColor': '#0288D1',
    'loopTextColor': '#0D47A1',
    'activationBkgColor': '#B3E5FC',
    'activationBorderColor': '#0277BD'
  }
}}%%

sequenceDiagram
    participant SAAS as 💳 SaaS Cash Register
    participant PP as 🔄 PingPong Acquiring Service

    Note over SAAS,PP: 💰 QR Code Payment Refund Process

    Note over SAAS, PP: 📋 Refund Request Parameters:• merchantTransactionId, merchantRefundId• cashierDeviceId

    SAAS->>+PP: 1. Refund Request (refund)
    
    PP->>PP: 2. Verify Request Signature and Parameters
    
    PP->>PP: 3. Process Refund Request
    
    Note over SAAS,PP: ✅ Refund Response:• transactionRefundId, merchantRefundId• status=ACCEPT_SUCCESS/PROCESSING
    
    PP-->>-SAAS: 4. Return Refund Acceptance Result
    
    opt 🔁 [Query Refund Result - Until Final State]
        Note over SAAS, PP: 🔎 Query Parameters:• refundId or merchantRefundId• merchantTransactionId
        
        SAAS->>+PP: 5. Refund Result Query (refund/query)
        
        PP->>PP: 6. Query Refund Status
        
        Note over SAAS,PP: 📊 Refund Status Response:• status=PROCESSING/SUCCESS/FAILED• Refund amount, currency, time and other information
        
        PP-->>-SAAS: 7. Return Refund Status Information
    end

    Note over SAAS,PP: 🎉 QR Code Refund Completed
```

### Initiate Refund Request
The SaaS cash register sends a refund request (refund) to the acquiring service
The request contains original transaction information and refund amount
Must include the `cashierDeviceId` parameter to identify the cash register itself

### Refund Processing
The acquiring service verifies the request and processes the refund operation
The refund result may not be returned immediately, initially may be `ACCEPT_SUCCESS` or `PROCESSING` status

### Result Query
The SaaS cash register obtains the final refund result through the refund query API (refund/query)
Polls for queries until the refund status becomes `SUCCESS` or `FAILED`

::: tip Refund Recommendation
For QR code payment refunds, it is recommended to retain the original transaction's `merchantTransactionId` in the system to quickly associate the original transaction during refund processing.
:::