Idempotency

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
Supported on the write endpoints that create resources - POST /v1/checkout, POST /v1/refunds, POST /v1/webhooks, and the billing POSTs (plans, customers, subscriptions, invoices, and their actions). 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 },
);

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

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

const session = await paybridgenp.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": {
    "message": "Concurrent request with same Idempotency-Key",
    "type": "idempotency_error",
    "code": "idempotency_conflict",
    "request_id": "req_..."
  }
}

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

Getting Started

Accepting Payments

Checkout

Providers

Subscriptions & Billing

Branding

Operations

Integrations

How it works

Key rules

Generating a UUID v4

Using with the SDK

Concurrent request conflict

When to use idempotency keys

​How it works

​Key rules

​Generating a UUID v4

​Using with the SDK

​Concurrent request conflict

​When to use idempotency keys

How it works

Key rules

Generating a UUID v4

Using with the SDK

Concurrent request conflict

When to use idempotency keys