Idempotent Requests

Network timeouts and dropped connections make it hard to know whether a request that creates a payment intent or refund actually went through. Idempotent requests let you retry safely: send the same request again with the same key and Slash returns the original result instead of creating a second payment intent or refund.

Using the `X-Idempotency-Key` header

Pass an X-Idempotency-Key header on POST /payments/payment-intent and POST /payments/refund. The key is any string you choose that uniquely identifies the operation on your side — an order id, a refund request id, or a UUID you store alongside the operation.

curl https://api.slash.com/payments/payment-intent \
  -X POST \
  -H "X-API-Key: $SLASH_API_KEY" \
  -H "X-Idempotency-Key: order_1234" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 5000, "currency": "usd", "metadata": { "orderId": "ord_1234" } }'

The header is optional. Requests without it are never deduplicated, so a retried request creates a new object every time.

How keys behave

Same key, same request — returns the previously created object. The response is a normal 200, so your retry logic can treat it exactly like a first-time success.
Same key, different request body — rejected. The key is bound to the parameters of the first request; you cannot reuse it to create a different payment intent or refund.
Scope — keys are scoped to your legal entity and to the endpoint. The same key string used on POST /payments/payment-intent and on POST /payments/refund refers to two different operations.

Payment Processing

Entities

Payment Intent

Refund

Idempotent Requests

Using the `X-Idempotency-Key` header

How keys behave

​Using the X-Idempotency-Key header

​How keys behave

Using the `X-Idempotency-Key` header

How keys behave