Idempotency

A network error can leave you unsure whether a request reached Kashu. An idempotency key makes the retry safe. Send the request again with the same Idempotency-Key header, and Kashu answers with the result of the first request instead of doing the work twice.

Send a key with every write

Pick a key that names the operation, such as order-1001-charge, and store it with the order, so a retry sends the same key. A key is 1 to 255 printable ASCII characters. Keys belong to your account and mode, so your keys never meet another account's.

Endpoints that move money require a key, and answer 400 idempotency_key_missing without one:

Group	Endpoint	What it does
Payment methods	POST `/v1/payment_methods`	Save a card for a customer from a single-use card token.
Payments	POST `/v1/payments`	Charge a saved card or a card token, or authorize it with capture_method manual. A decline is a payment with status failed.
Payments	POST `/v1/payments/{id}/capture`	Capture an authorized payment, once, for at most the amount held. Without an amount, all of it.
Payments	POST `/v1/payments/{id}/void`	Release an authorized payment that has not been captured.
Refunds	POST `/v1/refunds`	Refund part or all of a captured payment. Without an amount, all that is left.
Subscriptions	POST `/v1/subscriptions`	Bill a customer's saved card on a schedule. The first charge is made at once; it and every renewal arrive as payments that name the subscription.
Subscriptions	POST `/v1/subscriptions/{id}/cancel`	Cancel a subscription at the end of its period, or now with at_period_end false. Either way nothing more is billed after it ends.
Subscriptions	POST `/v1/subscriptions/{id}/resume`	Undo a cancel scheduled for the end of the period. A canceled subscription cannot be resumed.
Subscriptions	POST `/v1/subscriptions/{id}/charge_now`	Bill the subscription now if its next charge is due within 12 hours. Otherwise nothing is charged and it is returned unchanged.
Disputes	POST `/v1/disputes/{id}/evidence`	Send evidence for a dispute. Not available yet: every request answers feature_unavailable.
Disputes	POST `/v1/disputes/{id}/accept`	Accept a dispute and give up the disputed amount. Not available yet: every request answers feature_unavailable.
Checkout sessions	POST `/v1/checkout_sessions/{id}/pay`	Pay a checkout session with a card token. Kashu's card form calls this for you.

What a retry gets back

The same key with the same request answers with the same status and the same object, as the object is now. A payment captured since the first request comes back captured. The response carries Idempotent-Replayed: true.

A request Kashu refused, for example with parameter_invalid, answers the same error again. Fix the request and send it with a new key.

The same key with another body, or on another endpoint, answers 400 idempotency_key_reused.

While the first request still runs, a retry answers 409 idempotency_key_in_use. Wait a moment and retry. If the first request never finished, its key is free again after 60 seconds, and the next retry runs the request.

A 500 api_error frees the key too. Retry with the same key.

409 operation_in_progress means another request is changing the same object, such as a capture and a void sent together. Retry with the same key once the other request has finished.

When a payment says processing

processing means Kashu is waiting for the card network's answer. It is a normal state, not an error. Do not make a new payment for the same order. Retry with the same key, read the payment, or wait for its webhook: the payment moves to succeeded or failed on its own.

A payment that ends failed took no money, so you may then charge again, with a new key.