Idempotency

Network calls fail. When you retry POST /gateway/sessions/, you must not create a second payment for the same order. Paymee makes session creation idempotent through the merchant_reference field.

How it works

merchant_reference is your unique identifier for a payment (an order id, a cart id, an invoice number — whatever is stable on your side).

• The first request with a given merchant_reference creates the session and returns 201 Created.
• A subsequent request with the same merchant_reference returns the existing session with 200 OK — no duplicate is created.

# First call → 201 Created, new session
curl https://api.paymee.online/api/v1/gateway/sessions/ \
  -H "Authorization: Bearer sk_live_…" -H "Content-Type: application/json" \
  -d '{ "amount": "10.500", "merchant_reference": "order-0001", "first_name": "Aymen", "last_name": "Ben Salah", "email": "aymen@example.com" }'

# Same merchant_reference → 200 OK, the same session is returned

Guidelines

• Generate merchant_reference once per order, before the first attempt, and reuse it on every retry of that order.
• Use a new merchant_reference only when you genuinely want a new payment (e.g. the buyer is paying again after a failure that closed the session).
• Keep it unique per merchant account.

Tip

Because retries are safe, you can confidently retry on timeouts or 5xx responses without risking a double charge.

Conflicts

If a request conflicts with the current state of an existing session, you receive 409 Conflict as an RFC 9457 problem document, which may include an existing_session_id.