Web Rabbit Media — Payments, SMS & Custom Software

Network failures happen. Retrying a request without safeguards can double-charge a customer or send a charge twice. The Idempotency-Key header lets you retry safely.

How it works

Send a unique Idempotency-Key header (max 255 chars — a UUID is ideal) with any money-moving request. We store the response for 24 hours keyed by (business, endpoint, key). Retries with the same key return the original response with an Idempotent-Replayed: true header.

iSupported endpoints

POST /v1/collect/momo. Hosted checkout sessions and read endpoints don't need it (reads are already idempotent).

Example

shell

curl -X POST https://api.webrabbitmedia.com/v1/collect/momo \
  -H "Authorization: Bearer wr_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f4b7c1e-invoice-a104" \
  -d '{"amount": 10.50, "subscriber_number": "0240000000", "network": "MTN"}'

# Retry the exact same request:
# -> HTTP/2 201
# -> idempotent-replayed: true
# -> body is identical to the first response

Conflicts

Field	Type	Description
`Same key, same body, completed`	2xx	Original response is replayed with Idempotent-Replayed: true.
`Same key, same body, still in flight`	409	A request with this key is still in progress. Wait and retry.
`Same key, different body`	409	Idempotency-Key reused with a different request body. Pick a new key.
`Same key after 24h`	409	Key expired. Use a new one.

Recovering a lost transaction id

If the response to a POST is lost in transit you can look the transaction up by the Idempotency-Key you sent, without re-issuing the money-moving request:

shell

curl -H "Authorization: Bearer wr_live_..." \
  "https://api.webrabbitmedia.com/v1/transactions?idempotency_key=8f4b7c1e-invoice-a104"

# -> { "items": [ { "provider_transaction_id": "521888807466", "status": "approved", ... } ], ... }
# -> Empty items[] means we have no record — safe to retry the POST with the same key.

Best practices

Generate a UUID per business event (invoice id, order id) and reuse it across retries.
Set client-side timeouts to at least 30s — MoMo prompts can be slow.
Retry on network errors and 5xx. Do not retry on 4xx other than 429.
On a lost response, look up by idempotency_key before assuming failure.