Finalize a payout

Finalization is the step that makes a payout tamper-proof. Your organization’s signer signs the payout’s contents — after that, recipients, amounts, and schedule cannot change, and the payout can be funded but never altered.

import { createSignerFromPrivateKey } from '@pvium/sdk';

const signer = createSignerFromPrivateKey(process.env.PVIUM_SIGNER_KEY!);
const finalized = await payout.finalize(signer);

finalized.data.fundingUrl;  // checkout link for your treasury
finalized.data.batchHash;   // the signed payout hash
finalized.data.merkleRoot;  // commitment to the exact payment set

What finalization does

When you call payout.finalize(signer), the SDK:

Computes the payout hash from its funding token, timing rules, and rail.
Builds a Merkle tree over the exact payments, so each recipient’s claim is provable against the signed root.
Signs the result with your signer and stores the signature, hashes, and per-recipient proofs with the payout.

Because the signature commits to the full payment set, changing anything afterward invalidates it — this is the guarantee behind the “tamper-proof” note in the dashboard’s signing dialog. See Security.

The funding link

Open fundingUrl to fund the finalized payout in the dashboard (for example https://sandbox.pvium.com/batch/0x…). The page shows the signed payout details. Share the link with the person responsible for your treasury wallet so they can review the payout and authorize funding under your organization’s approval process.

Create and finalize in one call

For scheduled payouts, call pvium.payout.createFinalized to create and sign the payout in one call:

const finalized = await pvium.payout.createFinalized(
  {
    id: crypto.randomUUID(),      // required for createFinalized — must be a UUID
    chain: 'base-testnet',
    type: 'Scheduled',
    payoutCurrency: 'USDC',
    scheduleDate: 1753315200,
    payments: [{ receiver: '0xA1b2…', amount: 250 }],
  },
  signer,
);

Finalize options

Option	Purpose
`claimDate`	When recipients can start claiming
`gracePeriod`, `disapprovalDeadline`	Timing rules baked into the signed hash
`fundingToken`	Override the token the payout is funded in
`escrowBatch`	Fund a scheduled payout from a finalized pool (the pool must be finalized first)

Signers

Use your organization’s signing key to sign the payout finalization. To create or register this key, open your organization settings in the dashboard and go to the Signing Keys tab. See Signing keys for setup instructions.

createSignerFromPrivateKey(key) creates an EVM signer from a private key held in backend configuration.
Pass a custom signing function when your key lives elsewhere, such as an HSM or KMS.

Keep private signing keys on your backend or in your signing service. Anyone with access to the key can sign payout finalizations.

Payout keys

To let an automated service pay from a funded pool, authorize a payout key for that pool. Set a maximum amount per transaction, a maximum total amount, and an expiration. The service uses the payout key to make payments within those limits without access to your organization’s signing key.

Signing keys

The funding signer, payout keys, and how to authorize them from the dashboard or SDK.

Get started

Payout automation

Concepts

What finalization does

The funding link

Create and finalize in one call

Finalize options

Signers

Payout keys

Signing keys

​What finalization does

​The funding link

​Create and finalize in one call

​Finalize options

​Signers

​Payout keys

Signing keys

What finalization does

The funding link

Create and finalize in one call

Finalize options

Signers

Payout keys