TuCapiDocs

Fundamentals

Idempotency

Retry a POST without creating two charges, using the Idempotency-Key header.

How it works

Send the Idempotency-Key header on every POST. Your order number works.

  1. 1You create the charge with a key, for example ORD-1042.
  2. 2The connection drops and you don't know whether it was created.
  3. 3You retry with the same key and the same body.
  4. 4You get the same response, with the X-Idempotent-Replay: true header. No other charge is created.
curl -X POST https://api.business.tucapi.com/v1/charges \  -H "Authorization: Bearer $TUCAPI_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: ORD-1042" \  -d '{    "amount": "125.00",    "description": "Pedido #1042",    "reference": "ORD-1042",    "metadata": {      "customerId": "c_88"    },    "allowedMethods": [      "paypal",      "card"    ],    "expiresAt": "2026-09-16T12:00:00Z"  }'
Retry
HTTP/1.1 201 CreatedX-Idempotent-Replay: trueTuCapi-Api-Version: 2026-09-15

Rules

CaseResult
Same key, same bodyThe original response, with X-Idempotent-Replay: true.
Same key, different body409 idempotency_key_reused.
Same key while the first request is still running409 idempotency_in_flight. Retry in a few seconds.
Key longer than 255 characters400 idempotency_key_too_long.
  • A key is valid for 24 hours.
  • Keys are scoped per merchant and per endpoint.

Only successful responses are stored

If the first attempt ended in an error (a 400, a 409 reference_exists or a 500), a retry with the same key runs again.

The reference, a second safety net

Also send reference with your order number. It's unique per merchant.

Even if you change the key, there can't be two charges with the same reference: the second gets 409 reference_exists, and the message includes the existing charge's id.