Idempotency key

Send an Idempotency-Key header on every call that creates or moves money. If the connection drops before you read the answer, you resend the same request with the same key and get the original outcome back instead of a second charge or refund.

curl -X POST https://api-payments-staging.highwirepayments.com/v1/payments/auth-and-capture \
  -u "YOUR_API_KEY:YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0193c2e9-4f9a-7c2f-9c83-1b2b3c4d5e6f" \
  -d '{
    "amount": 7200,
    "cardNumber": "5555555555554444",
    "cardExpiration": "1133",
    "cardCvv": "456",
    "cardholderName": "Jordan Example",
    "cardholderEmail": "jordan@example.com",
    "cardholderPhone": "+14155550101",
    "cardholderBillingAddress": "100 Example Street",
    "cardholderBillingZipcode": "94105",
    "cardholderBillingCity": "Springfield",
    "cardholderBillingState": "CA"
  }'

Sending that request again with the same key and body, within 24 hours, replays the original response byte for byte: same status, same paymentId.

The header

• Name: Idempotency-Key. Optional, but strongly recommended on every write that accepts it.
• Value: 1 to 255 characters, any string. A fresh UUID (v4 or v7) per logical operation is the recommended format. There is no character-set rule.
• Send it once. A request carrying the header twice answers 400 Idempotency-Key header may only appear once per request; a value longer than 255 characters answers 400 Idempotency-Key must be 1..255 characters.
• Scope: your account, the endpoint and the path parameters together. The same key string on POST /v1/payments/{a}/refund and POST /v1/payments/{b}/refund is two different operations, and another account's keys never interfere with yours.
• Lifetime: 24 hours from the first call. After that the same string can be used for a new operation.
• Never put card data, e-mails or other personal identifiers in the key. It may appear in logs and support tools.

Which endpoints honour it

What a repeated call gets

After a 5xx

A 500 that says the operation was accepted is the exception: Capture accepted; finalization pending. Poll the payment., and the same message for a void or a refund. The processor has already taken the operation and only its recording is late. Do not retry it; poll the payment until it reflects the operation. A retry would only answer a plain 400 such as This payment has already been captured.

For any other 5xx:

1. Retry with the same key and body. The record was discarded, so the retry is processed, and a retry under the same key cannot create a duplicate charge: if the first attempt went through, you get that outcome back.
2. Expect that the retry may answer a plain 400 such as This payment has already been captured. or A refund is already in progress for this payment when the first attempt went through but could not be recorded. Read the payment with GET /v1/payments/{id} to confirm.
3. If retries keep failing, treat it as an outage and contact High Wire with the key and a timestamp so the operation can be reconciled. Do not move to a fresh key: a fresh key has no relation to the first attempt and can charge twice.

Choosing a key

• One key per logical operation: one per charge, one per refund of a given payment, one per checkout. Reuse it only to retry that same operation.
• Generate the key when the operation starts and keep it, with the request, in memory for the retry loop only. Never write card data (number, expiry, security code) to disk, a queue or a log in order to retry later. If your process is lost mid-request, read the payment back; if nothing was recorded, collect the card again.
• Composite keys such as order-8812-refund-1 work, but they make accidental reuse across operations easy, and that reuse answers 422 or, worse, replays an unrelated stored response.