Skip to content

Idempotency

Send an Idempotency-Key on merchant payment initiation to reserve one operation before Tinker Payments contacts a provider. Reusing the same key and payload reads that operation and never starts another provider request. Requests without this optional header use the existing initiation flow and have no durable replay guarantee.

Keys and retention

  • Use a new key for each new payment operation and save it with the original payload.
  • Keys are case sensitive, scoped to your authenticated app, and contain 1–128 visible ASCII characters without spaces.
  • Reuse the same key and payload after a timeout or lost response.
  • Changing the amount, currency, provider selection, customer details, reference, return URL, description, or metadata returns HTTP 409.
  • Reservations and saved responses persist across restarts. Keys do not expire automatically and cannot be recycled.
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",
  "customerEmail": "[email protected]"
}

Responses and retries

  • HTTP 200 returns the saved initiation data. A replay includes Idempotency-Replayed: true.
  • Payment-Operation-Id identifies the reserved operation on both HTTP 200 and HTTP 202.
  • HTTP 202 means execution is still in progress or the result is uncertain. Retry-After: 5 suggests when to read the same operation again using the same key and payload.
  • HTTP 400 rejects an invalid key. HTTP 409 rejects a changed payload. HTTP 503 means the reservation or saved response could not be accessed; reuse the same key.

A replay returns the original initiation data, including its original status and checkout URL. Response metadata may be fresh. Query the payment for its current completion status. The operation ID identifies initiation; use paymentReference to query a created payment.

HTTP 202: uncertain initiation
{
  "success": true,
  "data": {
    "operation_id": "8c6d6d48-3f24-4dc9-b302-b2df02302712",
    "execution_status": "unknown",
    "retry_allowed": false
  }
}

For an uncertain result, keep the same key. Creating a fresh key could create another payment. Keyed initiation currently uses one provider request with automatic routing retries and failover disabled. An uncertain operation stays reserved and requires resolution before further execution. Tinker Payments checks saved acceptance receipts and provider evidence without initiating another payment. Stripe checkout operations can recover a missing reference through bounded lookup or a signed callback. Unsupported lookup and exhausted checks appear in Payment investigations for operator follow-up. Open the operation in your dashboard using Payment-Operation-Id.

HTTP 409: changed payload
{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_PAYLOAD_MISMATCH",
    "message": "Idempotency-Key already used with a different request payload."
  }
}