Idempotency

Make retries safe - avoid duplicate payments when network failures occur.

Network failures happen. If your server sends a POST /v1/checkout request and the connection drops before you receive a response, you don’t know whether PayBridgeNP created the session or not. Retrying blindly can create duplicate checkout sessions for the same order.

PayBridgeNP supports idempotency keys on POST /v1/checkout to make retries safe.

How it works

Pass a unique Idempotency-Key header with your request:

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" }'

If the request succeeds, PayBridgeNP stores the key and response. If you retry with the same key, PayBridgeNP returns the original response without creating a new session - even if the original request completed successfully.

Key rules

• Use UUID v4 - random, unguessable, one per logical operation (not per HTTP request)
• Scope is per project - the same key can be reused across different projects
• Keys expire after 24 hours - after that, the same key creates a new session
• Only POST /v1/checkout supports idempotency keys - other endpoints are either idempotent by design (GET) or don’t benefit from this pattern

Generating a UUID v4

Node.js / Bun

import { randomUUID } from "crypto";

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

Using with the SDK

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

const paybridge = new PayBridgeNP({ apiKey: process.env.PAYBRIDGE_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 paybridge.checkout.create(
  {
    amount: 10000,
    returnUrl: "https://yoursite.com/success",
    metadata: { orderId },
  },
  { idempotencyKey },
);

On retry, pass the same key that was stored with the order:

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

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

Concurrent request conflict

If two requests with the same key arrive at exactly the same time, one of them will receive a 409 Conflict:

{
  "error": "Concurrent request with same Idempotency-Key",
  "code": "idempotency_conflict"
}

This is safe to retry after a short delay - it means a parallel request is already in flight.

When to use idempotency keys

Scenario	Use?
Server → PayBridgeNP API call on order submission	Yes
Client-side button that could be clicked twice	Yes - generate key server-side
Automated retry logic in your HTTP client	Yes
Polling GET /v1/payments/:id	No - GET is already safe to retry
Webhook handlers	No - use webhook deduplication on your side instead