Send your first payout

This walkthrough shows how to create and sign a payout with the TypeScript, Python, or Go SDK. You then use the returned funding link to fund the payout from your organization’s wallet and check its status.

Before you begin

An organization in the sandbox dashboard, with an API key and its client ID
A signer key for finalization, kept in backend configuration

To create the API key, open your organization settings in the sandbox dashboard and go to the API Keys tab. To create or register the signer key, go to the Signing Keys tab in the same settings. See Authentication and Signing keys for setup instructions.

Install the SDK

npm install @pvium/sdk

pip install pvium

go get github.com/pvium/sdks/go-sdk

Initialize

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

const pvium = PviumSdk.init({
  environment: 'sandbox',
  apiKey: process.env.PVIUM_API_KEY,
  clientId: process.env.PVIUM_CLIENT_ID,
});

from pvium_sdk import PviumSdk, PviumSdkConfig

pvium = PviumSdk.init(
    PviumSdkConfig(
        environment="sandbox",
        apiKey="your_api_key",
        clientId="your_client_id",
    )
)

package main

import (
    "context"
    "os"

    pvium "github.com/pvium/sdks/go-sdk"
)

func main() {
    sdk := pvium.Init(pvium.Config{
        Environment: pvium.EnvironmentSandbox,
        APIKey:      os.Getenv("PVIUM_API_KEY"),
        ClientID:    os.Getenv("PVIUM_CLIENT_ID"),
    })
    ctx := context.Background()
    // ...
}

Create a payout

Create an instant payout in USDC on Base testnet, paying receivers directly:

const payout = await pvium.payout.create({
  chain: 'base-testnet',
  type: 'Instant',
  payoutCurrency: 'USDC',
  label: 'July contributor payouts',
  payments: [
    { receiver: '0xA1b2…', amount: 250, memo: 'July retainer' },
    { receiver: '0xC3d4…', amount: 100, memo: 'Bug bounty' },
  ],
});

payout = pvium.payout.create(
    {
        "chain": "base-testnet",
        "type": "Instant",
        "payoutCurrency": "USDC",
        "label": "July contributor payouts",
        "payments": [
            {"receiver": "0xA1b2…", "amount": 250, "memo": "July retainer"},
            {"receiver": "0xC3d4…", "amount": 100, "memo": "Bug bounty"},
        ],
    }
)

payout, err := sdk.Payouts.Create(ctx, models.CreatePayoutInput{
    Chain:          "base-testnet",
    Type:           models.PayoutTypeInstant,
    PayoutCurrency: "USDC",
    Label:          "July contributor payouts",
    Payments: []models.PayoutPayment{
        {Receiver: "0xA1b2…", Amount: 250, Memo: "July retainer"},
        {Receiver: "0xC3d4…", Amount: 100, Memo: "Bug bounty"},
    },
}, nil)
if err != nil {
    log.Fatal(err)
}

Creating a payout saves its details without transferring funds. You can add, edit, or remove payments until you finalize it.

Add recipients by identity (optional)

Call addRecipients to add a recipient by a known identity, such as an email address or GitHub username. Pvium looks up the associated account and wallet:

const { added, errors } = await payout.addRecipients({
  recipients: [
    { identityType: 'github', identityValue: 'octocat', defaultPayoutAmount: 100 },
    { identityType: 'email', identityValue: 'dev@example.com', defaultPayoutAmount: 150 },
  ],
});

result = payout.addRecipients(
    {
        "recipients": [
            {"identityType": "github", "identityValue": "octocat", "defaultPayoutAmount": 100},
            {"identityType": "email", "identityValue": "dev@example.com", "defaultPayoutAmount": 150},
        ]
    }
)

githubAmount, emailAmount := 100.0, 150.0

result, err := sdk.Payouts.AddRecipients(ctx, payout.Data.ID, []models.PayoutRecipient{
    {IdentityType: "github", IdentityValue: "octocat", DefaultPayoutAmount: &githubAmount},
    {IdentityType: "email", IdentityValue: "dev@example.com", DefaultPayoutAmount: &emailAmount},
}, nil)
if err != nil {
    log.Fatal(err)
}

Recipients added this way must already be Pvium users — the identity resolves to their account and wallet, and the result separates added recipients from errors. Use resolveRecipients first to check who resolves. To pay someone who is not on Pvium yet, send them an invite instead. See Identity.

Finalize and get the funding link

Finalization signs the payout with your organization’s signer, locking recipients, amounts, and schedule:

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

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

console.log(finalized.data.fundingUrl);
// https://sandbox.pvium.com/batch/0x…

import os

finalized = payout.finalize(os.environ["PVIUM_SIGNER_KEY"])

print(finalized.fundingUrl)
# https://sandbox.pvium.com/batch/0x…

finalized, err := sdk.Payouts.Finalize(ctx, payout, os.Getenv("PVIUM_SIGNER_KEY"))
if err != nil {
    log.Fatal(err)
}

fmt.Println(finalized.Data.FundingURL)
// https://sandbox.pvium.com/batch/0x…

For scheduled payouts you can create and finalize in one call with createFinalized.

Fund the payout

Open the returned funding URL, or share it with the person responsible for your treasury wallet. Review the signed payout details on the page, then authorize funding from that wallet. Creating and finalizing the payout do not transfer funds. See Finalize a payout.

Track it

Poll the payout or list its payments:

const current = await pvium.payout.get(payout.id);
const payments = await payout.listPayments();

current = pvium.payout.get(payout.id)
payments = payout.listPayments()

current, err := sdk.Payouts.Get(ctx, payout.Data.ID, nil)
if err != nil {
    log.Fatal(err)
}
payments, err := sdk.Payouts.ListPayments(ctx, payout.Data.ID, nil, nil)

For push updates, configure a webhook on your organization.

Next steps

Create a payout

All payout types, chains, currencies, and payment fields.

Webhooks

Verify and handle payout lifecycle events.

Get started

Payout automation

Concepts

Send your first payout

Before you begin

Next steps

Create a payout

Webhooks

​Before you begin

​Next steps

Create a payout

Webhooks

Before you begin

Next steps