API Reference

Idempotency Key in Pockyt

1. What is an Idempotency Key?

An Idempotency Key is a unique identifier sent in a request to prevent the same operation from being processed more than once. This is useful in scenarios where network failures or delayed responses may cause clients to accidentally generate duplicate transactions.

2. Why Implement Idempotency Key ?

While Pockyt inherently prevents duplicate transaction processing even without an idempotency key (returning a 'Duplicate request error' for identical requests), implementing idempotency keys remains a critical best practice. By including a unique key, clients that experience network issues or retries will always receive the original transaction response exactly as first processed, rather than an error - ensuring reliable user experiences during connectivity interruptions or accidental resubmissions.

  • If a transaction has already been completed using a specific Idempotency Key, the API will return the same response without error response.
  • If the transaction has not been completed, the API will allow it to be executed normally.

3. How to Use Idempotency Key

Every time a client makes a request to an endpoint involving a transaction or a critical operation, they must include a header with the key Pockyt-Request-ID.

Example of a Valid Request

curl --request POST \
     --url https://mapi.pockyt.io/v3/payouts/pay \
     --header 'Pockyt-Request-ID: 123e4567-e89b-12d3-a456-426614174000' \//This is the idempotency key
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "merchantNo": "202333",
  "storeNo": "301854",
  "verifySign": "8b11e8f0d7f2a412f020f266110b57ba",
  "customerNo": "2000305228292319592008",
  "accountToken": "2010305228303182765718",
  "invoiceId": "9aae4c685d824c5da746f97620c59eb5",
  "amount": "500",
  "currency": "USD",
  "ipnUrl": "https://example.com/webhooks",
  "processingChannel": "STANDARD_ACH",
  "memo": "thank you",
  "note": "Cold drink",
  "subject": "Payouts"
}
'

✅ Strategies for Implementing Idempotency key


1️⃣ Using a Composite Idempotency Key (key_customerID_timestamp)

💡 Prevents collisions between transactions from different customers. (Max length: 64 characters)

Java Example: 

import java.util.UUID;

public class IdempotencyKeyGenerator {
    public static String generateKey(String customerId) {
        long timestamp = System.currentTimeMillis();
        return customerId + "_" + timestamp + "_" + UUID.randomUUID().toString();
    }

    public static void main(String[] args) {
        String customerId = "customer-123";
        String idempotencyKey = generateKey(customerId);
        System.out.println("Generated Idempotency Key: " + idempotencyKey);
    }
}

🔹 Explanation:

  1. The customerId ensures each customer has unique keys.
  2. A timestamp helps avoid collisions.
  3. A UUID adds further uniqueness.

2️⃣ Centralizing Idempotency Key Storage with Expiration

💡 Ensures that an ongoing customer transaction is not overwritten and prevents indefinite locks.

Java Example using Redis (Jedis)

import redis.clients.jedis.Jedis;

public class IdempotencyStorage {
    private static final String REDIS_HOST = "localhost"; // Update this based on your setup
    private static final int EXPIRATION_TIME = 300; // Key expires in 300 seconds (5 minutes)

    public static boolean storeIdempotencyKey(String key) {
        try (Jedis jedis = new Jedis(REDIS_HOST)) {
            Long result = jedis.setnx(key, "IN_PROGRESS");
            if (result == 1) { // If the key does not exist, store it with expiration
                jedis.expire(key, EXPIRATION_TIME);
                return true;
            }
            return false; // If the key exists, the transaction is already in progress
        }
    }

    public static void main(String[] args) {
        String key = "customer-123_17123456789";
        boolean stored = storeIdempotencyKey(key);
        System.out.println(stored ? "Key stored successfully!" : "Customer transaction already in progress.");
    }
}

🔹 Explanation:

  1. setnx ensures the key is only stored if it does not exist.
  2. expire sets a 5-minute expiration period.
  3. If the key exists, the customer transaction is rejected to avoid duplicates.

3️⃣ Applying a "Lock" Before Processing Customer Transactions

💡 Prevents two simultaneous processes from executing the same customer transaction.

Java Example using ReentrantLock

import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.locks.Lock;
import java.util.concurrent.locks.ReentrantLock;

public class TransactionProcessor {
    private static final ConcurrentHashMap<String, Lock> locks = new ConcurrentHashMap<>();

    public static void processTransaction(String idempotencyKey) {
        locks.putIfAbsent(idempotencyKey, new ReentrantLock());
        Lock lock = locks.get(idempotencyKey);

        if (lock.tryLock()) {
            try {
                System.out.println("Processing customer transaction with key: " + idempotencyKey);
                Thread.sleep(2000); // Simulate transaction processing
                System.out.println("Customer transaction completed: " + idempotencyKey);
            } catch (InterruptedException e) {
                e.printStackTrace();
            } finally {
                lock.unlock();
                locks.remove(idempotencyKey);
            }
        } else {
            System.out.println("Customer transaction already in progress: " + idempotencyKey);
        }
    }

    public static void main(String[] args) {
        String key = "customer-123_17123456789";
        processTransaction(key);
    }
}

🔹 Explanation:

  1. Uses ReentrantLock to prevent simultaneous execution of the same transaction.
  2. tryLock() ensures that only one process can execute a transaction at a time.
  3. If tryLock() fails, another process is already handling the transaction.

🛡️ Idempotency Security Checklist

🔑 Key Generation

  • customerID + timestamp + UUID
  • Never expose raw customer IDs

🗃️ Storage

  • DB atomic operation with expiration (e.g., SETNX, INSERT IF NOT EXISTS)
  • Encrypt keys if containing PII
  • Default TTL: 5min (payments), 72h (refunds)

🔒 Security

  1. Env vars for config (REDIS_HOST, AES_KEY)
  2. Rate limiting per customer (jedis.incr)
  3. Audit logs for duplicates

⚠️ Avoid

  • Hardcoded credentials
  • Keys in URLs/logs
  • Infinite key retention

✅ Merchant Action: Test collision handling!