Idempotency Keys

Overview

When making API requests that create resources (checkouts, installment requests), network issues or timeouts may cause you to miss the response even though JeelPay successfully processed the request. Without protection, retrying such a request would create a duplicate — resulting in the customer receiving multiple payment links.

Idempotency keys solve this problem. By including a unique key with your request, JeelPay guarantees that retrying the same request will return the original response without creating a duplicate.

---

How It Works

1. Generate a unique string (we recommend a UUID) and send it as the Idempotency-Key header.

2. JeelPay processes the request and caches the response against your key.

3. If you retry with the same key, JeelPay returns the cached response — no new resource is created.

4. If you send a different key, JeelPay treats it as a new request.

Keys are scoped to your group (API credentials) and the specific endpoint, meaning key-123 on /v3/checkout/schooling and key-123 on /v3/checkout are treated independently.

Key Expiration: Idempotency keys are automatically cleaned up after 24 hours. After that, the same key can be reused.

---

Recommended Integration Flow

To ensure data consistency, we recommend creating a record in your database before calling the JeelPay API. This ensures you always have the Idempotency Key saved to retry in case of a timeout.

---

Supported Endpoints

Endpoint	Method	Description
/v3/checkout/schooling	POST	Create a schooling checkout
/v3/checkout	POST	Create an items checkout
/v2/installment-requests	POST	Create an installment request

---

Usage

Add the Idempotency-Key header to your request. The value must be a unique string (max 255 characters).

Example — Schooling Checkout

curl -X POST https://api.jeel.co/v3/checkout/schooling \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "buyer": { ... },
    "students": [ ... ],
    "urls": { ... },
    "metadata": { "orderId": "ORD-123" },
    "referenceId": "ref-001"
  }'

Example — Items Checkout

curl -X POST https://api.jeel.co/v3/checkout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -d '{
    "buyer": { ... },
    "items": [ ... ],
    "urls": { ... },
    "metadata": { "orderId": "ORD-123" },
    "referenceId": "ref-001"
  }'

Example — Installment Request (V2)

curl -X POST https://api.jeel.co/v2/installment-requests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-456" \
  -d '{ ... }'

---

Retry Behavior

Scenario	Result
First request with Idempotency-Key: abc	Checkout/request is created, response is returned and cached
Retry with Idempotency-Key: abc (same key)	Cached response returned — no duplicate created
New request with Idempotency-Key: xyz (different key)	A new checkout/request is created
Request without Idempotency-Key header	Request is processed normally (no caching)

---

Best Practices

1. Always send an idempotency key on checkout and installment request creation endpoints.

2. Use UUIDs — they are globally unique and easy to generate in any language.

3. Generate a new key for every distinct request — do not reuse keys across different intended requests.

4. Store the key alongside your order/transaction so you can correlate retries.

5. Implement proper retry logic — on timeout or 5xx errors, retry with the same idempotency key.

Key Generation Examples

// JavaScript / Node.js
const idempotencyKey = crypto.randomUUID();

# Python
import uuid
idempotency_key = str(uuid.uuid4())

// Java
String idempotencyKey = UUID.randomUUID().toString();

// PHP
$idempotencyKey = wp_generate_uuid4(); // WordPress
// or
$idempotencyKey = \Ramsey\Uuid\Uuid::uuid4()->toString();

---

FAQ

Is the Idempotency-Key header required? No, it is optional. However, we strongly recommend always including it to protect against duplicate resource creation during timeouts.

What happens if I don't send the header? The request is processed normally. If a timeout occurs and you retry, a duplicate checkout or installment request will be created.

How long is a key valid? Keys expire after 24 hours. After expiration, the same key value can be reused for a new request.

Can I use the same key across different endpoints? Yes — keys are scoped per endpoint. The key abc on /v3/checkout/schooling is independent from abc on /v3/checkout.

What if the original request failed with a validation error? Only successful responses (HTTP 200) are cached. If the original request failed, retrying with the same key will process the request again.