Skip to main content
The creates that move money or make a record you might make twice take a required Idempotency-Key header. If a response is lost, send the same request again with the same key: it answers what the first attempt made, and never takes payment or refunds twice. The header follows the IETF Idempotency-Key draft:
A write without a key says in its reference whether it’s safe to repeat, and lists OUTCOME_UNKNOWN among its errors where it may take effect without saying so.

Keys

  • A key is 1 to 255 printable ASCII characters, with no spaces, quotes or backslashes. We recommend a UUID.
  • Send it in double quotes, as the draft defines. We also accept it without them.
  • A missing key answers 400 IDEMPOTENCY_KEY_REQUIRED.
  • A key belongs to your account and the endpoint, not to a token, so a new token or a rotated secret doesn’t affect a retry. A partner and its merchant are separate accounts, so the same key sent with each credential starts two requests.
  • The same key on another endpoint is a separate request.
  • Keys are kept for at least 7 days. After that, the same key starts a new request.

Choosing a Key

Make one key for each thing you mean to happen once, and store it with your own record of that thing before you send the request. A retry then sends the same key whether it comes a second later or after your process has crashed and started again. A key made at the moment of sending and kept only in memory protects a retry inside that one process. After a crash, the next attempt makes a new key, and the API can’t tell it from a new request. That matters most where nothing else stops a second record: Repeating these creates with a new key does no harm: For a payment transaction, store the key with the attempt, not with the order. When the customer tries again after a payment transaction has failed or been cancelled, make a new key: a replay answers the payment transaction as it now stands, so the old key keeps answering the one that failed, for at least the 7 days keys are kept.

Retrying with the Same Key

Sending the same key to the same endpoint with a different path or body answers 422 IDEMPOTENCY_KEY_REUSED.

A First Attempt That Never Finished

A first attempt can stop partway, leaving its key with no outcome. Once that has lasted 5 minutes, what a retry does depends on the endpoint: Either way, a retry never takes payment or refunds twice. A second payment transaction or payment link moves no money unless a customer pays it, and a refund’s key is never taken over. A retry goes through the same authentication and permission checks as any other request.

One-Time Values

Some values appear only in the response that issues them: a secret, or a link that carries a token. A response holding one is sent with Cache-Control: no-store, so don’t cache it, and store the value yourself if you need it. A one-time value isn’t stored, so a replayed response leaves it out. A create you sent once can be answered as a replay too, when a dropped connection inside Quidkey lost its first answer and Quidkey sent it on again. So check for the value rather than assume it. If a create’s answer has no checkout, call :issueCheckout, and if a webhook endpoint’s has no signing_secret, call :rotateSecret. Each value has its own way back: A payment link’s checkout and qr_code aren’t one-time: a replayed create and a read both return them, while the link is open. Treat them as secrets all the same, because anyone holding the URL can pay.

Concurrency

Two requests with the same key at once run one create: the second answers 409 IDEMPOTENCY_IN_PROGRESS. A create you sent once can answer it too, when Quidkey sent it on again while the first attempt was still running: wait a moment, then send it again with the same key. Resources don’t take If-Match. Money routes are protected by locks and status checks instead: a refund created while another request is working on the same payment transaction answers 409 PAYMENT_BUSY.