Idempotency

Use idempotency keys when retrying create or money-moving POST requests. If your first request times out, retry with the same key and the same body.

import { Ionic } from "@ionicfi/sdk";

const ionic = new Ionic({ token: process.env.IONIC_SECRET_KEY });

const session = await ionic.checkout.sessions.create({
  "Idempotency-Key": "order_1001_checkout",
  mode: "payment",
  line_items: [
    { name: "Starter plan", amount: 2900, currency: "usd", quantity: 1 },
  ],
  success_url: "https://example.com/success",
  cancel_url: "https://example.com/cancel",
});

curl https://api.ionicfi.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: order_1001_checkout" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "payment",
    "line_items": [
      {
        "name": "Starter plan",
        "amount": 2900,
        "currency": "usd",
        "quantity": 1
      }
    ],
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }'

How it works

Send a stable Idempotency-Key for one business operation.
Reuse that key only when retrying the same request.
If the original request completed, Ionic returns the original result.
If the same key is reused with a different body or endpoint, Ionic rejects the request.

For PaymentIntent creation, confirmation, and Refund creation, the key remains associated with the original operation if the response is lost or the result is unknown. Retrying can recover that operation’s current result. A timeout does not authorize a second charge or refund. While the result remains unknown, inspect the original resource and wait for reconciliation. After a confirmed decline or failure, a separately permitted payment attempt uses a new key. Reusing the original key retrieves the original attempt. A new key does not bypass an unresolved attempt on the same PaymentIntent. Completed keys normally remain available for 24 hours. Unresolved payment operations retain their association beyond that window; do not rotate keys to work around an unknown result. A key is not a permanent order-level uniqueness constraint. Replayed responses include:

Idempotent-Replayed: true

Conflict behavior

Status	Code	Meaning
`400`	`IDEMPOTENCY_KEY_TOO_LONG`	Header is longer than 255 characters.
`409`	`IDEMPOTENCY_KEY_IN_PROGRESS`	Another request with this key is still running.
`422`	`IDEMPOTENCY_BODY_MISMATCH`	Same key, different body.
`422`	`IDEMPOTENCY_ROUTE_CONFLICT`	Same key, different endpoint.
`503`	`IDEMPOTENCY_STORE_UNAVAILABLE`	The API cannot safely deduplicate the request.

Key design

Use a key derived from your own operation ID, not a random key generated per retry. Good:

order_1001_create_checkout_session

Avoid:

checkout

Fundamentals

Payments

Checkout

In-person payments

Customers and catalog

Connect

Billing

Webhooks

How it works

Conflict behavior

Key design

​How it works

​Conflict behavior

​Key design

How it works

Conflict behavior

Key design