Retry requests safely
Use an idempotency key so a retry can't create a second payment instance, payment link or payment plan.
A request can time out after the server has already done the work. To retry without creating a
duplicate, send an Idempotency-Key header on POST /instances, POST /links and POST /plans.
- Generate a key for the operation, not for the attempt. Tie it to your own record, such as
order-10428-link. A key has 8 to 128 characters. - Send the key with the request.
- If the request fails or times out, send the same request with the same key.
curl -X POST https://api.mytpe.app/api/ext/links \
-H "Authorization: Bearer $MYTPE_ACCESS_TOKEN" \
-H "Idempotency-Key: order-10428-link" \
-H "Content-Type: application/json" \
-d '{ "payment_instance_id": "your-instance-id", "title": "Order 10428", "amount_mode": "fixed", "amount": 4500, "usage_mode": "one_shot" }'What happens on a retry
| Situation | Response |
|---|---|
| The first request succeeded | The first response, with Idempotent-Replayed: true. |
| The first request is still running | 409 with IDEMPOTENCY_IN_PROGRESS. Wait and retry. |
| The same key with a different body | 409 with IDEMPOTENCY_KEY_REUSED. |
| The first request was refused | MyTPE runs the request again, because a refusal isn't remembered. |
Keys belong to your account, and MyTPE keeps them for 7 days.
The header is optional. Without it, each retry of POST /links creates another link, and each retry
of POST /plans creates another plan and emails the customer again. POST /instances without a key
returns the activation still pending for the same details, but use a key anyway.
Postman collection