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)
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
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 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