---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/InPersonPayments/offlineQRCodePayment/index.md
description: >-
  线下二维码支付解决方案通过SAAS收银机与POS设备云端通信，实现支付、查询和退款。采用REST
  API方式，支持支付宝、微信等移动支付工具。关键API包括下单、交易查询、申请退款和退款查询。适用于零售场景，二维码有效期可自定义，建议设置为5分钟以优化用户体验。
---
# 线下二维码支付

## 主要参与方

PingPongCheckout的线下二维码支付解决方案实现了SAAS收银机与POS设备通过云端服务进行通信，完成支付、查询、退款等交易流程。该方案采用REST API方式，生成二维码供消费者使用移动支付工具完成支付。

- SAAS收银机：发起交易请求，展示二维码，接收交易结果
- PingPong收单服务：处理请求，生成二维码，通知交易结果
- 消费者移动设备：扫描二维码完成支付

## API 清单

1. <a href="/notes/zh/api/services/InPersonPayments/unifiedPay/" target="_blank">下单 API</a>
2. <a href="/notes/zh/api/services/InPersonPayments/paymentQuery/" target="_blank">单笔交易查询 API</a>
3. <a href="/notes/zh/api/services/InPersonPayments/refund/" target="_blank">申请退款 API</a>
4. <a href="/notes/zh/api/services/InPersonPayments/refundQuery/" target="_blank">退款查询 API</a>

## 支付流程

```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收银机
    participant PP as 🔄 PingPong收单服务
    participant Consumer as 📱 消费者移动设备

    Note over SAAS,Consumer: 🧾 二维码支付流程

    Note over SAAS, PP: 📋 请求参数:• cashierDeviceId• paymentMethod=二维码支付方式• timeExpire (二维码有效期)

    SAAS->>+PP: 1. 下单并支付请求(unifiedPay)
    
    PP->>PP: 2. 验证请求签名和参数
    
    Note over PP,Consumer: ✅ 二维码响应:• qrCode, qrUrl, qrCodeExpired• status=PROCESSING
    
    PP-->>-SAAS: 3. 返回二维码信息

    SAAS->>Consumer: 4. 向消费者展示二维码

    Consumer->>Consumer: 5. 扫描二维码

    Consumer->>Consumer: 6. 确认支付

    Consumer->>PP: 7. 支付处理

    opt 🔁 [轮询订单状态 - 直到终态]
        Note over SAAS, PP: 🔎 查询参数:• transactionId 或 merchantTransactionId
        
        SAAS->>+PP: 8. 订单结果查询(query)
        
        PP->>PP: 9. 查询订单状态
        
        Note over PP,Consumer: 📊 订单状态响应:• status=PROCESSING/SUCCESS/FAILED
        
        PP-->>-SAAS: 10. 🔟 返回订单状态信息
    end

    Note over SAAS,Consumer: 🎉 二维码支付完成
```

### 发起支付请求
SAAS收银机向PingPong收单服务发送统一下单支付请求(unifiedPay)
请求中必须包含`cashierDeviceId`参数标识收银机自身
指定`paymentMethod`参数为相应的二维码支付方式

::: note 注意
请求参数中的`timeExpire`表示二维码的有效期，可设置1分钟到3天。若不设置，默认为3天。
为提高用户体验，建议设置合理的二维码超时时间，通常零售场景建议设置为5分钟。
:::

### 生成二维码
PingPong收单服务接收请求并验证签名
生成支付二维码，返回`qrCode`和`qrUrl`参数
同时返回`qrCodeExpired`参数表示二维码过期时间

### 展示二维码
SAAS收银机接收响应，将二维码展示给消费者
消费者使用移动支付工具（如支付宝、微信等）扫描二维码完成支付

### 支付结果查询
初始响应状态通常为`PROCESSING`
SAAS收银机需通过查询API(query)轮询订单状态
或等待PingPong收单服务通过`notificationUrl`推送支付结果

::: warning 重要提示
收单服务返回的初始状态为`PROCESSING`，只表示二维码生成成功，不代表支付完成。
SAAS收银机应实施轮询机制，建议间隔3-5秒查询一次，直到获取最终支付结果。
:::

## 退款流程

```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收银机
    participant PP as 🔄 PingPong收单服务

    Note over SAAS,PP: 💰 二维码支付退款流程

    Note over SAAS, PP: 📋 退款请求参数:• merchantTransactionId, merchantRefundId• cashierDeviceId

    SAAS->>+PP: 1. 退款请求(refund)
    
    PP->>PP: 2. 验证请求签名和参数
    
    PP->>PP: 3. 处理退款请求
    
    Note over SAAS,PP: ✅ 退款响应:• transactionRefundId, merchantRefundId• status=ACCEPT_SUCCESS/PROCESSING
    
    PP-->>-SAAS: 4. 返回退款受理结果
    
    opt 🔁 [查询退款结果 - 直到终态]
        Note over SAAS, PP: 🔎 查询参数:• refundId 或 merchantRefundId• merchantTransactionId
        
        SAAS->>+PP: 5. 退款结果查询(refund/query)
        
        PP->>PP: 6. 查询退款状态
        
        Note over SAAS,PP: 📊 退款状态响应:• status=PROCESSING/SUCCESS/FAILED• 退款金额、币种、时间等信息
        
        PP-->>-SAAS: 7. 返回退款状态信息
    end

    Note over SAAS,PP: 🎉 二维码退款完成
```

### 发起退款请求
SAAS收银机向收单服务发送退款请求(refund)
请求中包含原交易信息和退款金额
必须包含`cashierDeviceId`参数标识收银机自身

### 退款处理
收单服务验证请求并处理退款操作
退款结果可能不会立即返回，初始可能为`ACCEPT_SUCCESS`或`PROCESSING`状态

### 结果查询
SAAS收银机通过退款查询API(refund/query)获取最终退款结果
轮询查询直到退款状态变为`SUCCESS`或`FAILED`

::: tip 退款建议
对于二维码支付的退款，建议在系统中保留原交易的`merchantTransactionId`，以便在退款时快速关联原交易。
:::