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
Payment Process
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
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
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
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
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.