Idempotency

Use idempotency keys for write operations to guarantee at-most-once execution for the same logical request. This is required for safe retries during network timeouts and transient upstream failures.

How It Works

  • Send a unique Idempotency-Key header per logical operation.
  • Reuse the same key when retrying the exact same payload.
  • If the same key is reused with a different payload, the API rejects the request.
  • Store keys client-side with request correlation IDs for auditability.
POST https://api.tinkerpayments.com/v1/merchant/payment/initiate
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: 8cb5e5f2-6d5f-4f0b-9d0a-2412f7746f15

{
  "amount": 100.00,
  "currency": "USD",
  "gateway": "stripe",
  "merchantReference": "ORDER-12345",
  "returnUrl": "https://your-app.com/payment/return"
}
Idempotency conflict response
{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_PAYLOAD_MISMATCH",
    "message": "Idempotency-Key already used with a different request payload."
  }
}