Idempotency

Reuse the same payout ID when retrying a create request. This prevents a timeout or network error from causing your retry to create a second payout.

Supply your own payout ID

create accepts an optional id — a client-generated ID the new payout is created under. It must be a UUID (the API validates this); if omitted, the server generates one. For idempotency, don’t use a random UUID per attempt — derive a deterministic UUID (v5) from the thing that makes the payout unique in your system, such as an invoice ID or payroll period, so every retry produces the same id:

import { v5 as uuidv5 } from 'uuid';

const PAYOUT_NAMESPACE = 'f3b1c9d2-0000-4000-8000-000000000000'; // any fixed UUID

const payout = await pvium.payout.create({
  id: uuidv5('payroll-2026-07', PAYOUT_NAMESPACE), // same input → same UUID, every retry
  chain: 'base',
  type: 'Instant',
  payoutCurrency: 'USDC',
  payments,
});

createFinalized requires a payout id. Reuse that ID on retries so you can look up the payout if the original response is lost.

Create a local payout run first

For automated payout runs that add payees to a funded pool or escrow, create a local payout-run record before calling Pvium. Store a durable UUID on that local record, then pass it as finalizeOptions.id when you call addPayments. That UUID becomes the linked scheduled child payout ID in Pvium. If the request succeeds but your worker times out before it sees the response, retry with the same local record and the same finalizeOptions.id instead of generating a fresh payout.

const localRun = await db.payoutRuns.upsert({
  key: "rewards:" + period,
  payoutId: deterministicUuid,
  status: "submitting",
  payments,
});

try {
  await pvium.payout.addPayments(fundedPool.data, {
    payments: localRun.payments,
    signer,
    finalizeOptions: {
      id: localRun.payoutId,
      claimDate,
    },
  });
} catch (error) {
  const existing = await pvium.payout.get(localRun.payoutId);
  // If the payout exists and belongs to this pool, continue from it.
}

The API uses that id as the payout batch primary key. A duplicate retry will not create a second child payout, but it also will not replay the original response. Treat the duplicate or ambiguous error as a recovery path: fetch pvium.payout.get(id), verify it belongs to the expected parent pool or escrow, then mark your local run complete.

Individual payments

Within a batch, a payment’s identity is (batch, receiver, memo) — enforced by a unique constraint.

The same receiver can appear on multiple rows in one batch as long as each row carries a distinct memo. Put your per-payment business key in the memo — an invoice code or installment identifier like INV-1042:install-3 — and each obligation becomes its own idempotent row.
Re-adding the same (receiver, memo) never creates a second payment: a direct add is rejected as a duplicate, and an invite-driven attach updates the existing row’s amount in place.
A retried add-payments call therefore cannot double-pay anyone — the repeated rows collide on (batch, receiver, memo) instead of duplicating.

Nonces

Every payout also carries a nonce. The SDK generates one automatically; pass your own only if you need the nonce to be deterministic across systems.

Retry pattern

Compute the payout id from your business key before calling Pvium.
On a timeout or network error, retry the same call with the same id.
A retried create whose id already exists is rejected as a duplicate — it will not create a second payout, and it will not return the existing one. Catch the conflict, fetch the payout with pvium.payout.get(id), and continue from its current state — it may already be created or even finalized.
Key webhook processing on payout and payment IDs, so re-deliveries are no-ops. See Webhooks.

What finalization adds

Finalization is naturally idempotent in effect: it signs the payout’s exact contents, and funding accepts only that signed payout. Even if your retry logic misfires at the create step, nothing can be paid twice from one funding — the checkout funds the signed payment set, once.

Get started

Payout automation

Concepts

Supply your own payout ID

Create a local payout run first

Individual payments

Nonces

Retry pattern

What finalization adds

​Supply your own payout ID

​Create a local payout run first

​Individual payments

​Nonces

​Retry pattern

​What finalization adds

Supply your own payout ID

Create a local payout run first

Individual payments

Nonces

Retry pattern

What finalization adds