TagPayTagPay

Getting started

Idempotency

Networks fail, requests time out, and responses get lost. Idempotency keys let you safely retry mutations without creating duplicate charges, refunds, or transfers.

Why idempotency matters

Imagine you call POST /v1/transactions/initialize to charge a customer NGN 5,000. TagPay processes the charge and the customer is debited — but your connection drops before the response gets back to you. You don't know if the charge succeeded.

If you retry the request blindly, you double-charge. If you don't retry, you don't know whether to fulfill the order. Idempotency removes the dilemma: retries with the same key return the same result, every time.

The Idempotency-Key header

Send a unique value in the Idempotency-Key request header. A UUID v4 is the standard choice — generate one per logical request and reuse it across all retries of that request:

curl https://gwt.tagpay.ng/v1/checkout/sessions \
  -H "Authorization: Bearer $TAGPAY_SECRET_KEY" \
  -H "Idempotency-Key: f7c1d8e2-4a3b-4f9a-9c8d-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500000, "reference": "ord_1184", "customer_email": "[email protected]"}'

Retention window

Idempotency keys are retained for 24 hours from first use. Within that window, the same key replayed with the same body returns the original response — bit-for-bit, including the HTTP status code.

After 24 hours the key is purged. A request with that same key after expiry is treated as a new request and will create a new resource.

Behavior on replay

  • Same key, same operation within 24h → cached response, bit-for-bit identical to the first call. The body is not re-validated, so reuse the same key only for retries of the same logical request.
  • Same key, different operation (e.g. same key on POST /v1/transactions/initialize and then on POST /v1/refunds) → 409 IDEMPOTENCY_KEY_MERCHANT_MISMATCH. The key is scoped to (merchant, method, path); collisions across endpoints are refused.
  • No key on a mutation → request proceeds, but retries are unsafe.

Best practices

  • Generate one UUID v4 per logical request — never reuse for a different operation.
  • Persist the key alongside your business record before issuing the request. On retry, read the stored key and resend.
  • Keep keys to 1–255 characters. UUIDs are 36, which is ideal.
  • Pair idempotency with exponential backoff on 429 and 5xx — see Errors.