Essentials

Idempotent requests

Retry payouts and bill payments safely. The same Idempotency-Key never moves money twice.

Networks fail in the worst place: after Lint has sent your payout but before your server hears back. Retrying blindly could pay twice. An Idempotency-Key makes the retry safe.

How it works

Send a unique key in the Idempotency-Key header. The first request with that key runs normally and Lint stores its response. Any retry with the same key and the same body within 24 hours gets the stored response back — same status, same body — and nothing runs again. Replayed responses carry Idempotent-Replayed: true.

curl

curl -X POST https://staging.lint.finance/api/partner/v1/wallets/initiate-transfer \
  -H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: payout-2026-11-02-000123" \
  -d '{
    "debit_wallet_id": "209bc13c-70ce-450d-8f2e-7a870362912a",
    "credit_account_number": "5010880910",
    "credit_account_bank_code": "999240",
    "amount": 1000000,
    "currency": "NGN",
    "remark": "Invoice 8812"
  }'

Idempotency keys are supported on the two calls that move money out:

POST /wallets/initiate-transfer — payouts
POST /vas/billers/create-order — bill payments

Choosing keys

Use a value tied to the thing you are paying for, generated before the first attempt and stored with it — your payout or order ID works well, or a UUID you save. Then every retry of that payment sends the same key, even after a crash or redeploy. Keys can be up to 255 characters and are scoped to your account.

What gets stored

First request ended with	Stored?	A retry with the same key
Success (`2xx`)	Yes	Gets the same response
An error after the work started (`insufficient_balance`, `provider_error`, `500`…)	Yes	Gets the same error. Fix the cause, then use a new key.
`validation_failed`, `unauthenticated`, `bvn_not_verified` or `rate_limited`	No	Runs normally. The key was not used up.

Storing errors is deliberate: once a payout has started, money may have moved even if the response was an error, and replaying the outcome is the only safe answer.

Errors specific to idempotency

HTTP	`code`	Meaning
409	`idempotency_key_in_progress`	The first request with this key is still running. Wait a moment and retry with the same key.
422	`idempotency_key_reused`	The key was used with a different body. A key belongs to one request; use a new one.
400	`invalid_idempotency_key`	The key is longer than 255 characters.

Note

A replayed response is the original byte for byte, so its request_id is the first request's. The X-Request-Id header identifies the retry itself.