Idempotency

Every request can be repeated safely. Creates use your merchant_reference; capture and void are safe by the status of the payin. Reads change nothing and can be repeated as they are.

Request	Idempotent by
POST /v2/payins/card, /apple-pay, /google-pay, /blik	merchant_reference
POST /v2/pay-sessions	merchant_reference
POST /v2/payins/{payin_id}/refunds	merchant_reference of the refund
POST /v2/payouts/card	merchant_reference
POST /v2/payins/{payin_id}/capture, /void	The status of the payin
POST /v2/payins/apple-pay/sessions	Creates nothing — repeat as is

Creates: merchant_reference

merchant_reference is your id for the transaction and its idempotency key. Generate it once, save it, then call.

You send	You get
A new merchant_reference	It is created: 201
The same reference, the same body	The existing one in its current status: 201 with Idempotent-Replayed: true. Nothing is performed twice
The same reference, a different body	409 merchant_reference_conflict. Nothing is performed

• The body is compared as JSON: the order of keys and whitespace do not matter.
• It never expires and is unique per merchant across payins, refunds, payouts and pay sessions.
• A pay session and the payin created from it share one merchant_reference: the payin gets the reference of its session.
• A final transaction keeps its reference. A new attempt after failed is a new transaction with a new merchant_reference.

capture and void

A repeat while the action is in progress, or after it, returns the payin in its current status; nothing is performed twice. After payin.capture_failed or payin.void_failed the payin is authorized again, and a new call is a new attempt (R5).

Retrying

After a timeout or a dropped connection the outcome is unknown. Resend the identical request — the same reference and body. Never a new one, never a second transaction "to be safe".

Lost the response and not sure what you sent? Find the transaction with GET /v2/transactions?merchant_reference=…. A pay session is found by resending its create: the payin appears only after the payer submits the form.

Repeating from a new request on your side

The payer clicks Pay again, or your process restarted after sending the create. The new request carries new card data, and you must not store card numbers or CVC to replay the original.

1. GET /v2/transactions?merchant_reference=…. Found — use it, do not create.
2. Not found — create with the new data.
3. 409 merchant_reference_conflict — an earlier request created it in the meantime: go to 1.

Next: Errors