---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/InPersonPayments/offlineCardPayment/index.md
description: >-
  The offline card payment solution enables payment, query, and refund functions
  through cloud communication between SAAS cash registers and POS devices. Using
  REST API methods, key parameters include deviceSn, deviceModel, and
  cashierDeviceId to ensure transaction requests are accurately routed to
  designated POS terminals. Covers scenarios including instant payments and
  refund processing in physical stores, supporting both card swipe and NFC
  payment methods.
---
## Main Participants

PingPongCheckout's offline card payment solution integration enables communication between SAAS cash registers and POS devices through cloud services to complete payment, query, refund, and other transaction processes. This solution uses REST API methods and ensures transaction requests are accurately routed to designated POS terminals through clear device identification mechanisms.
    
- SAAS Cash Register: Initiates transaction requests and receives transaction results
- PingPong Acquiring Service: Acts as middleware, handling request routing and response forwarding
- POS Device: Executes actual payment operations and processes card transactions

## API List

1. <a href="/en/notes/api/services/InPersonPayments/unifiedPay/" target="_blank">Payment 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 POS as 📱 POS Device

    Note over SAAS, POS: 💰 Card Payment Process

    Note over SAAS, PP: 📋 Request Parameters:• deviceSn, deviceModel, cashierDeviceId• paymentMethod=card payment method

    SAAS->>+PP: 1. Payment request (unifiedPay)
    
    PP->>PP: 2. Verify request signature and parameters
    
    PP->>+POS: 3. Forward payment request to designated POS device
    
    POS->>POS: 4. Execute card swipe/NFC payment operation
    
    Note over PP, POS: ✅ Payment Response:• Contains card transaction information (cardTransinfo)• transactionId, merchantTransactionId• status=SUCCESS/FAILED
    
    POS-->>-PP: 5. Return payment processing result
    
    PP-->>-SAAS: 6. Return payment result
    
    opt 🔍 [Query order details]
        Note over SAAS, PP: 🔎 Query parameters:• transactionId or merchantTransactionId
        
        SAAS->>+PP: 7. Order result query (query)
        
        PP->>PP: 8. Query order status
        
        Note over PP, POS: 📊 Order details response:• Complete cardTransinfo information• Acquiring bank, card number, cardholder information, etc.
        
        PP-->>-SAAS: 9. Return order details
    end

    Note over SAAS, POS: 🎉 Payment process completed
```

### Initiate Payment Request
The SAAS cash register sends a unified payment request (unifiedPay) to the PingPong acquiring service
The request contains `deviceSn` and `deviceModel` parameters to clearly specify the target POS device
Also includes `cashierDeviceId` to identify the cash register itself

::: note Note
The `deviceSn`, `cashierDeviceId`, and `deviceModel` parameters ensure payment requests are correctly routed to the designated POS device. Please ensure parameters are filled correctly,
otherwise it may cause payment failure or requests to be routed to the wrong POS device
:::

### Request Routing
The PingPong acquiring service receives the request and verifies the signature
Routes the payment request to the designated POS device based on `deviceSn` and `deviceModel`

### Payment Processing
The POS device receives the request and executes the payment operation (such as card swipe, NFC payment, etc.)
After processing is complete, the POS device returns the result to the acquiring service

### Result Return
The acquiring service returns the payment result to the SAAS cash register. The synchronous response result may be `PROCESSING` status, and the payment result needs to be obtained through the query API,
The SAAS cash register receives the result and performs subsequent processing (such as printing receipts, updating order status, etc.)

## 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  
    participant POS as 📱 POS Device

    Note over SAAS, POS: 💰 Card Payment Refund Process

    Note over SAAS, PP: 📋 Refund Request Parameters:• merchantTransactionId, merchantRefundId• deviceSn, deviceModel (required for POS refund)

    SAAS->>+PP: 1. Refund request (refund)
    
    PP->>PP: 2. Verify request signature and parameters
    
    PP->>+POS: 3. Forward refund request to designated POS device
    
    POS->>POS: 4. Execute refund operation
    
    Note over PP, POS: ✅ Refund Response:• transactionRefundId, merchantRefundId• status = ACCEPT_SUCCESS/PROCESSING/SUCCESS/FAILED
    
    POS-->>-PP: 5. Return refund processing result
    
    PP-->>-SAAS: 6. Return refund acceptance result
    
    opt 🔍 [Query refund status - Optional]
        Note over SAAS, PP: 🔎 Query parameters:• refundId or merchantRefundId• merchantTransactionId
        
        SAAS->>+PP: 7. Refund result query (refund/query)
        
        PP->>PP: 8. Query refund status from database
        
        Note over PP, POS: 📊 Refund status response:• status = PROCESSING/SUCCESS/FAILED• Refund amount, currency, time, etc.
        
        PP-->>-SAAS: 9. Return refund status information
    end

    Note over SAAS, POS: 🎉 Refund process completed
```

### Initiate Refund Request

The SAAS cash register sends a refund request (refund) to the acquiring service
For POS transaction refunds, `deviceSn` and `deviceModel` parameters must be included
The request contains original transaction information and refund amount

### Refund Routing

The acquiring service verifies the request and routes it to the designated POS device
The POS device executes the refund operation

### Result Return
The POS device returns the refund result to the acquiring service. The synchronous response result may be `PROCESSING` status, and the payment result needs to be obtained through the query API,
The acquiring service returns the refund acceptance result to the cash register