---
title: Transaction Idempotency
permalink: /en/notes/onlinePayment/bestPractices/paystatus/
createTime: '2025/03/07 16:01:49'
description: 'Understand idempotency logic for order transactions in different scenarios.'
---

## Idempotency Modes

There are two supported idempotency modes, you can choose the appropriate idempotency mode from below:

1. <a href="/en/notes/technicalterm/FailureFinalState/" target="_blank">Non-Failure Final State (default)</a>  
2. <a href="/en/notes/technicalterm/FailureFinalState/" target="_blank">Failure Final State</a>  

## Transaction Status List

The following are possible transaction statuses that may be returned in different scenarios:

### Automatic Capture
| Status                                                           | Description                                     |
|:-----------------------------------------------------------------|:-----------------------------------------------|
| `SUCCESS`    | Payment successful, transaction successful     |
| `CLOSED`     | Transaction result due to timeout/closure      |
| `FAILED`     | Payment failed, user can retry payment         |
| `CANCEL`     | Risk control review rejected, final state      |
| `PROCESSING` | Intermediate state, merchant should wait for PingPongCheckout asynchronous result before business processing. |
| `INIT`       | Order initialization                          |

### Manual Capture

| Status                                                                | Description                                                     |
|:----------------------------------------------------------------------|:---------------------------------------------------------------|
| `SUCCESS`      | Final CAPTURE successful                                        |
| `AUTH_SUCCESS` | AUTH operation successful, still need to initiate CAPTURE operation |
| `CLOSED`       | Transaction result due to timeout/closure                       |
| `FAILED`       | Payment failed, user can retry payment                          |
| `CANCEL`       | AUTH operation successful, calling VOID for pre-authorization void |
| `PROCESSING`   | Intermediate state, cannot initiate CAPTURE operation, merchant should wait for PingPongCheckout asynchronous result before business processing. |
| `INIT`         | Order initialization                                           |

## Order Lifecycle

```mermaid
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#2196F3',
    'primaryTextColor': '#FFFFFF',
    'primaryBorderColor': '#1976D2',
    'lineColor': '#1565C0',
    'secondaryColor': '#E3F2FD',
    'tertiaryColor': '#BBDEFB',
    'background': '#F8FBFF',
    'mainBkg': '#E3F2FD',
    'nodeBorder': '#1976D2',
    'clusterBkg': '#F5F5F5',
    'clusterBorder': '#1976D2',
    'titleColor': '#0D47A1'
  }
}}%%

flowchart TB
    subgraph AutoCapture["📦 Automatic Capture (captureDelayHours=0)"]
        direction TB
        A1([🚀 Create Order]) --> A2[INIT<br/>Initialize]
        A2 -->|Payment Request| A3[PROCESSING<br/>Processing]
        A3 -->|Transaction Failed| A4[FAILED<br/>Payment Failed]
        A3 -->|Transaction Success| A5[SUCCESS<br/>Payment Success]
        A3 -->|Timeout Close| A6[CLOSED<br/>Order Closed]
        A2 -->|Timeout Close| A6
    end

    subgraph ManualCapture["🔧 Manual Capture (captureDelayHours=-1)"]
        direction TB
        B1([🚀 Create Order]) --> B2[INIT<br/>Initialize]
        B2 -->|Payment Request| B3[PROCESSING<br/>Processing]
        B3 -->|Auth Success| B4{Auth<br/>Success?}
        B4 -->|Yes| B5[AUTH_SUCCESS<br/>Pre-auth Success]
        B4 -->|No| B6[FAILED<br/>Payment Failed]
        B5 -->|Request VOID| B7[CANCEL<br/>Pre-auth Cancelled]
        B5 -->|Capture| B8{Capture}
        B8 -->|Capture Success| B9[SUCCESS<br/>Payment Success]
        B8 -->|Capture Failed| B10[Capture Failed]
        B10 -->|Request Refund<br/>Cannot Request| B11[Refund Success/Failed<br/>Transaction Cannot Recover]
        B2 -->|Timeout Close| B12[CLOSED<br/>Order Closed]
    end

    style A1 fill:#2196F3,stroke:#1976D2,color:#FFFFFF
    style A5 fill:#4CAF50,stroke:#388E3C,color:#FFFFFF
    style A4 fill:#F44336,stroke:#D32F2F,color:#FFFFFF
    style A6 fill:#9E9E9E,stroke:#757575,color:#FFFFFF
    style B1 fill:#2196F3,stroke:#1976D2,color:#FFFFFF
    style B5 fill:#4CAF50,stroke:#388E3C,color:#FFFFFF
    style B9 fill:#4CAF50,stroke:#388E3C,color:#FFFFFF
    style B6 fill:#F44336,stroke:#D32F2F,color:#FFFFFF
    style B7 fill:#FF9800,stroke:#F57C00,color:#FFFFFF
    style B12 fill:#9E9E9E,stroke:#757575,color:#FFFFFF

```

Status Transition Description

+ The following statuses will send transaction asynchronous notifications:
  - `SUCCESS`
  - `FAILED`
  - `CANCEL`
+ For scenarios where transaction status is not in the above status list, the order API or query interface will synchronously respond with `PROCESSING`, merchants should wait for PingPongCheckout asynchronous result before business processing.<br><br>

+ When the merchant sends the order closure notification URL (closeNotificationUrl) in the order placement interface, an order closure asynchronous notification will be sent after the order is closed:
  - `CLOSED`
+ This status is the order's final state. This notification is associated with merchantTransactionId (merchant transaction ID) to ensure accurate tracking and identification of specific orders.

## Order Association Relationship

```mermaid
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#2196F3',
    'primaryTextColor': '#FFFFFF',
    'primaryBorderColor': '#1976D2',
    'lineColor': '#1565C0',
    'secondaryColor': '#E3F2FD',
    'tertiaryColor': '#BBDEFB',
    'background': '#F8FBFF',
    'mainBkg': '#E3F2FD',
    'nodeBorder': '#1976D2'
  }
}}%%

erDiagram
    PAYMENT_ORDER ||--o{ PAYMENT_REQUEST : "1:N"
    PAYMENT_ORDER ||--o{ REFUND_ORDER : "1:N"
    PAYMENT_REQUEST ||--o| VOID_REQUEST : "1:1"
    PAYMENT_REQUEST ||--o{ CAPTURE_REQUEST : "1:N"
    PAYMENT_REQUEST ||--o{ REFUND_REQUEST : "1:N"

    PAYMENT_ORDER {
        string merchantTransactionId PK "Payment Order ID"
        string status "Order Status"
    }

    PAYMENT_REQUEST {
        string requestId PK "Payment Request ID"
        string status "Request Status"
    }

    REFUND_ORDER {
        string refundId PK "Refund Order ID"
        string status "Refund Status"
    }

    VOID_REQUEST {
        string voidId PK "Void Request ID"
        string status "Void Status"
    }

    CAPTURE_REQUEST {
        string captureId PK "Capture Request ID"
        string status "Capture Status"
    }

    REFUND_REQUEST {
        string refundRequestId PK "Refund Request ID"
        string status "Refund Status"
    }

```

## Transaction Idempotency Rules

+ Payment orders require merchantTransactionId (merchant website order number) to be globally unique; if duplicate orders are placed, the system will idempotently return the payment order information. (Cashier Mode)
+ Payment requests are uniquely identified by merchantTransactionId + requestId; if duplicate payment requests are made, the system will idempotently return the payment request status information (S2S Mode)

Based on the above idempotency rules, we provide some retry windows (see detailed <a href="/en/notes/guide/bestPractices/rescue/" target="_blank">Transaction Recovery</a>)