Idempotency

How it works

curl -X POST https://api.paybridgenp.com/v1/checkout \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10000, "returnUrl": "https://yoursite.com/success" }'

Key rules

• Use UUID v4 - random, unguessable, one per logical operation (not per HTTP request)
• Keys are scoped to your project and live or sandbox mode
• Responses are retained for at least 24 hours - never reuse a key for a different operation
• A key belongs to one request - sending a key you already used with a different endpoint or method returns 409 with code idempotency_key_already_used, and nothing runs. The invoice endpoints refuse a different body the same way. On the other endpoints, the same key sent again to the same endpoint with a different body still returns the first response; treat that as a bug in your integration, because it will be refused too in a future change
• Limit refusals are not stored - a request refused because of a plan limit (402), a feature your plan does not include, a rate limit (429), or a spend cap is evaluated again when you retry with the same key, so it can succeed once the limit clears. Other error responses, such as validation errors, are returned again as they were
• Supported on these endpoints - POST /v1/checkout, POST /v1/mobile/session, POST /v1/refunds, POST /v1/webhooks, POST /v1/payment-links, POST /v1/qr/fonepay, POST /v1/qr/{id}/refresh, and these billing endpoints: POST /v1/billing/plans, /customers, /customers/{id}/credit, /subscriptions, /subscriptions/{id}/invoice-items, /invoices/{id}/qr, /coupons, /promotion-codes, and /dunning/policies. Other write endpoints ignore the header. GET requests are idempotent by design and ignore the key

Generating a UUID v4

import { randomUUID } from "crypto";

const idempotencyKey = randomUUID();
// "550e8400-e29b-41d4-a716-446655440000"

const idempotencyKey = crypto.randomUUID();

$idempotencyKey = \Ramsey\Uuid\Uuid::uuid4()->toString();
// or: bin2hex(random_bytes(16))

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

Using with the SDK

import { randomUUID } from "crypto";
import { PayBridgeNP } from "@paybridge-np/sdk";

const paybridgenp = new PayBridgeNP({ apiKey: process.env.PAYBRIDGENP_API_KEY! });

// Generate the key once and store it with your order
const idempotencyKey = randomUUID();
await db.orders.update({ idempotencyKey }, { where: { id: orderId } });

const session = await paybridgenp.checkout.create(
  {
    amount: 10000,
    returnUrl: "https://yoursite.com/success",
    metadata: { orderId },
  },
  idempotencyKey,
);

const order = await db.orders.findOne({ where: { id: orderId } });

const session = await paybridgenp.checkout.create(
  { amount: order.amount, returnUrl: "...", metadata: { orderId } },
  order.idempotencyKey, // same key and same request = same response
);

Concurrent request conflict

{
  "error": {
    "message": "Concurrent request with same Idempotency-Key",
    "type": "idempotency_error",
    "code": "idempotency_conflict",
    "request_id": "req_..."
  }
}

Key reused for a different request

{
  "error": {
    "message": "This Idempotency-Key was already used for a different request.",
    "type": "idempotency_error",
    "code": "idempotency_key_already_used",
    "request_id": "req_..."
  }
}

When to use idempotency keys