#Idempotency

Network calls fail. Idempotency lets you safely retry a request that creates something — a payment, a payment link — without accidentally creating it twice.

#How it works

Attach an Idempotency-Key header to any POST. If PlutoPay has already processed a request with that key for your account, it returns the original result instead of doing the work again — and echoes the key back on the response.

curl https://plutopayus.com/api/v1/transactions \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_1001" \
  -d '{ "amount": 4750, "currency": "usd", "payment_method_type": "card" }'

• First call → creates the transaction, returns 201.
• Repeat with the same key → returns the existing transaction with 200 and a note: "Idempotent request - returning existing transaction."
• Every response echoes the header back: Idempotency-Key: order_1001.

The header works on every mutating /v1 endpoint. On POST /v1/transactions, a legacy idempotency_key body field is still accepted for backward compatibility, but the header is preferred.

#Best practices

• Generate a unique key per logical operation — e.g. your internal order id, optionally suffixed (order_1001:charge). Reusing a key for a different operation returns the first result, which is probably not what you want.
• Keep keys stable across retries of the same operation, and different across distinct operations.
• Safe to retry with the same key: 429 (rate limited) and 5xx (server) responses. Do not blindly retry 4xx validation errors — fix the request first.