Idempotency | API Docs

Networks fail. Retry a create with the same request, and Weav returns the payment or checkout the first one made, never a second one. Your external_reference_id is the key, so there’s nothing extra to send.

HTTP

POST /v1/payments
Authorization: Bearer wv_test_••••••••
Content-Type: application/json

{ "channel": "QR_PH", "currency": "PHP", "amount": 1250.00, "external_reference_id": "ORD-10541" }

Rules

On POST /v1/payments and POST /v1/checkouts. The rules work the same way for a checkout.
Same external_reference_id and same body: you get the payment that request created, with the same 201 and the same fields, as it is now (so its status may have moved on), plus the header Idempotent-Replayed: true.
Same external_reference_id and a different body: 409 with code 4090001. A reference belongs to one payment: if a customer retries an order, send a new reference such as ORD-10541-2.
A reference that an earlier payment already has under another key: 422 with code 4220000 (errors names external_reference_id). This happens when the first request sent an Idempotency-Key and the retry doesn’t, or sent a different one. Retry exactly as you sent the first request, or use a new reference for a new payment.
Same request while the first one is still running: 409 with code 4090002. Wait and retry.
A request that creates nothing (for example it fails validation) leaves the reference unused, so you can fix the cause and retry.
Test and live mode are separate.
A checkout’s external_reference_id is optional. A checkout with no reference and no Idempotency-Key is never matched to an earlier one, so each request makes a new checkout.

flowchart LR
    K{Reference<br/>used before?} -->|No| N[201<br/>created]
    K -->|Yes| B{First request<br/>still running?}
    B -->|Yes| W[409, 4090002<br/>wait, then retry]
    B -->|No| S{Same body?}
    S -->|Yes| RP[201, the same one<br/>Idempotent-Replayed]
    S -->|No| CF[409, 4090001<br/>use a new reference]

Your own key (optional)

To use your own key, send an Idempotency-Key header, such as a new UUID for each new payment and the same one for every retry of it (up to 255 characters). Weav then matches retries on that key instead, with the same rules. Use one or the other for a payment, not both: a retry without the key you sent first is a new request, and its reference is already taken (422).

HTTP

Idempotency-Key: 7d1f6c0e-2b4a-4c9e-9f3d-6a1b8e2c5f10