---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/InPersonPayments/offlineCardPayment/index.md
description: >-
  线下卡支付解决方案通过SAAS收银机与POS设备云端通信，实现支付、查询、退款等功能。采用REST
  API方式，关键参数包括deviceSn、deviceModel和cashierDeviceId，确保交易请求准确路由至指定POS终端。覆盖场景包括实体店铺的即时支付与退款处理，支持刷卡及NFC支付方
---
## 主要参与方

PingPongCheckout的线下卡支付解决方案集成方案实现了SAAS收银机与POS设备通过云端服务进行通信，完成支付、查询、退款等交易流程。该方案采用REST API方式，通过明确的设备标识机制确保交易请求准确路由到指定的POS终端。
    
- SAAS收银机：发起交易请求，接收交易结果
- PingPong收单服务：作为中间层，处理请求路由和响应转发
- POS设备：执行实际的支付操作，处理卡片交易

## 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 POS as 📱 POS设备

    Note over SAAS, POS: 💰 卡支付流程

    Note over SAAS, PP: 📋 请求参数:• deviceSn, deviceModel, cashierDeviceId• paymentMethod=卡支付方式

    SAAS->>+PP: 1. 下单并支付请求(unifiedPay)
    
    PP->>PP: 2. 验证请求签名和参数
    
    PP->>+POS: 3. 转发支付请求到指定POS设备
    
    POS->>POS: 4. 执行刷卡/NFC支付操作
    
    Note over PP, POS: ✅ 支付响应:• 包含卡交易信息(cardTransinfo)• transactionId, merchantTransactionId• status=SUCCESS/FAILED
    
    POS-->>-PP: 5. 返回支付处理结果
    
    PP-->>-SAAS: 6. 返回支付结果
    
    opt 🔍 [查询订单详情]
        Note over SAAS, PP: 🔎 查询参数:• transactionId 或 merchantTransactionId
        
        SAAS->>+PP: 7. 订单结果查询(query)
        
        PP->>PP: 8. 查询订单状态
        
        Note over PP, POS: 📊 订单详情响应:• 完整的cardTransinfo信息• 收单行、卡号、持卡人等信息
        
        PP-->>-SAAS: 9. 返回订单详情
    end

    Note over SAAS, POS: 🎉 支付流程完成
```

### 发起支付请求
SAAS收银机向PingPong收单服务发送统一下单支付请求(unifiedPay)
请求中包含`deviceSn`和`deviceModel`参数，明确指定目标POS设备
同时包含`cashierDeviceId`标识收银机自身

::: note 注意
`deviceSn`,`cashierDeviceId`和`deviceModel`参数是为了确保支付请求被正确路由到指定的POS设备,  请确保参数填写正确,
否则可能导致支付失败或请求被路由到错误的POS设备
:::

### 请求路由
PingPong收单服务接收请求并验证签名
根据`deviceSn`和`deviceModel`将支付请求路由到指定POS设备

### 支付处理
POS设备接收请求并执行支付操作(如刷卡、NFC支付等)
处理完成后，POS设备将结果返回给收单服务

### 结果返回
收单服务将支付结果返回给SAAS收银机,同步响应结果可能是`PROCESSING`状态,支付结果需要通过查询API进行获取,
SAAS收银机接收结果并进行后续处理（如打印小票、更新订单状态等）

## 退款流程

```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 POS as 📱 POS设备

    Note over SAAS, POS: 💰 卡支付退款流程

    Note over SAAS, PP: 📋 退款请求参数:• merchantTransactionId, merchantRefundId• deviceSn, deviceModel (POS退款必传)

    SAAS->>+PP: 1. 退款请求(refund)
    
    PP->>PP: 2. 验证请求签名和参数
    
    PP->>+POS: 3. 转发退款请求到指定POS设备
    
    POS->>POS: 4. 执行退款操作
    
    Note over PP, POS: ✅ 退款响应:• transactionRefundId, merchantRefundId• status = ACCEPT_SUCCESS/PROCESSING/SUCCESS/FAILED
    
    POS-->>-PP: 5. 返回退款处理结果
    
    PP-->>-SAAS: 6. 返回退款受理结果
    
    opt 🔍 [查询退款状态 - 可选]
        Note over SAAS, PP: 🔎 查询参数:• refundId 或 merchantRefundId• merchantTransactionId
        
        SAAS->>+PP: 7. 退款结果查询(refund/query)
        
        PP->>PP: 8. 从数据库查询退款状态
        
        Note over PP, POS: 📊 退款状态响应:• status = PROCESSING/SUCCESS/FAILED• 退款金额、币种、时间等信息
        
        PP-->>-SAAS: 9. 返回退款状态信息
    end

    Note over SAAS, POS: 🎉 退款流程完成
```

### 发起退款请求

SAAS收银机向收单服务发送退款请求(refund)
对于POS交易退款，必须包含`deviceSn`和`deviceModel`参数
请求中包含原交易信息和退款金额

### 退款路由

收单服务验证请求并路由到指定POS设备
POS设备执行退款操作

### 结果返回
POS设备将退款结果返回给收单服务，同步响应结果可能是`PROCESSING`状态,支付结果需要通过查询API进行获取,
收单服务将退款受理结果返回给收银机