Idempotency Integration Guide for Payment Systems

1. Definition

Idempotency ensures that multiple identical requests to a payment interface (under the same conditions) yield the same result as a single request. It eliminates risks like duplicate transactions, redundant deductions, or inconsistent order status caused by network retries, system timeouts, or concurrent calls.

2. Applicable Methods

This guide applies exclusively to POST, PUT, and PATCH methods for payment-related interfaces.

• GET: Query-only (e.g., payment status checks) – inherently idempotent, no extra handling needed.
• DELETE: Cancel operations (e.g., payment order cancellation) – inherently idempotent, no extra handling needed.

3. Integration Rules

3.1 Exceptions to Idempotency Checks

Idempotency verification will NOT be triggered if:

1. The request lacks the Idempotency-Key header.
2. The request method is not POST/PUT/PATCH.
3. The request payload does not contain accountId.

3.2 Core Constraints

• Global Uniqueness: The combination of account_id, Idempotency-Key, and request_uri must be unique across the entire payment system.
• Concurrent Requests: Returns “transaction in progress” if concurrent identical requests are detected.
• Result Consistency: All repeated requests return the result of the first successful request.
• Data Retention: Idempotency records are stored for 90 days (for audit and dispute resolution).

4. How to Use Idempotency-Key

4.1 Key Generation

Clients must generate a unique Idempotency-Key for each new payment request (e.g., UUID v4).

4.2 Key Transmission

Include the key in the request header:

Using OkHttp Library

import okhttp3.*;
import java.io.IOException;
import java.util.UUID;

public class PaymentClientOkHttp {
    
    private static final MediaType JSON = MediaType.get("application/json; charset=utf-8");
    
    public void createPaymentOrder() {
        try {
            // Generate unique idempotency key
            String idempotencyKey = UUID.randomUUID().toString();
            
            // Create request body
            String requestBody = """{
                "accountId": "ACC123456",
                "amount": 100.00,
                "currency": "USD"
            }""";
            
            // Build HTTP client and request
            OkHttpClient client = new OkHttpClient();
            Request request = new Request.Builder()
                .url("https://payment-gateway.com/api/v1/payments/create-order")
                .addHeader("Content-Type", "application/json")
                .addHeader("Idempotency-Key", idempotencyKey)
                .post(RequestBody.create(requestBody, JSON))
                .build();
            
            // Send request
            try (Response response = client.newCall(request).execute()) {
                System.out.println("Status Code: " + response.code());
                System.out.println("Response Body: " + response.body().string());
            }
            
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

Maven Dependencies

For OkHttp, add this dependency to your pom.xml:

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.12.0</version>
</dependency>