> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quidkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Send a create again with the same Idempotency-Key, and recover what it did instead of doing it twice

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](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/):

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/merchants/m_1/transactions' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

| Endpoint | Key |
| - | - |
| `POST /partners/{id}/merchants` | Required |
| `POST /legal-entities/{id}/parties` | Required |
| `POST /merchants/{id}/bank-accounts` | Required |
| `POST /merchants/{id}/transactions` | Required |
| `POST /merchants/{id}/payment-links` | Required |
| `POST /transactions/{id}/refunds` | Required |
| `POST /merchants/{id}/webhook-endpoints` | Required |
| `POST /partners/{id}/webhook-endpoints` | Required |

A write without a key says in its reference whether it's [safe to repeat](https://docs.quidkey.com/api-v1/standards/errors.md#safe-to-repeat), and lists `OUTCOME_UNKNOWN` among its errors where it [may take effect without saying so](https://docs.quidkey.com/api-v1/standards/errors.md#unknown-outcomes).

## 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:

| Create | One key for each | A second key makes |
| - | - | - |
| `POST /merchants/{id}/transactions` | Attempt to pay an order | A second payment transaction for the order |
| `POST /transactions/{id}/refunds` | Refund you mean to make | A second refund, while the payment transaction has enough left to refund |
| `POST /merchants/{id}/payment-links` | Link you mean to send | A second link a customer can pay |
| `POST /legal-entities/{id}/parties` | Person or company you're adding | The same party twice |
| `POST /merchants/{id}/bank-accounts` | Account you're adding | The same bank account twice |

Repeating these creates with a new key does no harm:

| Create | A second key |
| - | - |
| `POST /partners/{id}/merchants` | Is refused with 409 `MERCHANT_ALREADY_EXISTS`: a merchant can't be made twice |
| `POST /merchants/{id}/webhook-endpoints` | Is refused with 409 `WEBHOOK_ENDPOINT_NAME_EXISTS` for an endpoint with the same name |
| `POST /partners/{id}/webhook-endpoints` | Is refused with 409 `PARTNER_WEBHOOK_ENDPOINT_EXISTS`: a partner has one endpoint |

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

| What happened first | What the retry answers |
| - | - |
| It succeeded | The first attempt's status, such as 201, with the resource **as it now stands**, and an `Idempotent-Replayed: true` header. |
| It failed, or was refused, such as with a 400, a 409 or a 429 | No outcome is kept for a request that failed, so the retry runs the request again. |
| It's still running | 409 `IDEMPOTENCY_IN_PROGRESS`. Wait, then send it again. |
| It answered `SERVICE_UNAVAILABLE` | Send the same request with the same key: it answers the first attempt's outcome if there was one, and otherwise runs it. |

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:

| Endpoint | What a retry does |
| - | - |
| A payment transaction, a payment link, a merchant, a webhook endpoint | It takes the key over and runs the request again. If the first attempt had made its record, a payment transaction or payment link is made a second time, unpaid, and the retry answers with the second. A merchant or webhook endpoint can't be made twice, so there the retry answers the 409 a duplicate gets: `MERCHANT_ALREADY_EXISTS`, `WEBHOOK_ENDPOINT_NAME_EXISTS` or `PARTNER_WEBHOOK_ENDPOINT_EXISTS`. |
| A refund, a party, a bank account | It answers 409 `IDEMPOTENCY_IN_PROGRESS`, however long it has been. Contact Quidkey support if it persists. |

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:

| Value | Issued by | To get it again |
| - | - | - |
| `checkout` on a payment transaction | `POST /merchants/{id}/transactions` | `POST /transactions/{id}:issueCheckout`, with a credential of the payment transaction's owner: the partner that created it, while the merchant is still with that partner, and otherwise the merchant. It answers the same live token. |
| `signing_secret` on a webhook endpoint | The endpoint's create, `:rotateSecret`, or a `PATCH` that turns signing on | `POST /webhook-endpoints/{id}:rotateSecret`, which replaces the secret at once. |
| `hosted_link` on an identity check | `POST /parties/{id}:verifyIdentity` | Call `:verifyIdentity` again. |

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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.