Skip to main content

​
Developer Quickstart

Use the PayChainHQ SDK or REST API from a trusted backend. Never expose API keys in browsers, mobile apps, static sites, or public client code.
Important note: PayChain API keys are backend secrets. Do not put them in frontend JavaScript, mobile apps, public GitHub repos, support screenshots, logs, or analytics tools.
Docs positioning: The SDK is the fastest path for Node.js and TypeScript. REST examples are available in REST API guide and Payment flows.

​
Install the SDK

npm install @paychainhq/sdk

import { PayChain } from '@paychainhq/sdk';

const paychain = new PayChain({
  apiKey: process.env.PAYCHAIN_API_KEY!,
  businessId: process.env.PAYCHAIN_BUSINESS_ID!,
  environment: 'live'
});

​
Create a customer

const customer = await paychain.customers.create({
  externalRef: 'customer_123',
  email: 'payer@example.com'
});

​
Create an invoice

Flow note: This is the fixed amount invoice flow. For auto-detected payments, payout route invoices, dynamic payout recipients, and programmatic withdrawals, see Payment flows.
const invoice = await paychain.invoices.create(
  {
    amount: '100.00',
    token: 'USDC',
    chain: 'evm',
    networkId: 'base-mainnet',
    customerId: customer.id
  },
  { idempotencyKey: 'order_123_invoice' }
);

​
Attach a payout route

await paychain.invoices.create(
  {
    amount: '100.00',
    token: 'USDC',
    chain: 'evm',
    networkId: 'base-mainnet',
    payoutRouteId: 'route_123'
  },
  { idempotencyKey: 'order_124_invoice' }
);

​
Dynamic payout recipients

Dynamic recipients are for trusted backend payout automation, usually with a payout API key. The SDK accepts percentages and converts them to basis points for the API.
Payout key note: Dynamic payout recipients can move money after invoice settlement. Use a payout API key and apply your own order-level validation before sending destination addresses to PayChain.
await paychain.invoices.create(
  {
    amount: '100.00',
    token: 'USDC',
    chain: 'evm',
    networkId: 'base-mainnet',
    payoutRecipients: [
      { label: 'Seller', destinationAddress: '0x0000000000000000000000000000000000000000', percentage: 90 },
      { label: 'Platform', destinationAddress: '0x0000000000000000000000000000000000000000', percentage: 10 }
    ]
  },
  { idempotencyKey: 'order_125_invoice' }
);

​
Verify webhooks

PayChain sends webhooks when an invoice, withdrawal, or routing event changes state. Your backend should verify every webhook before acting on it. Verification must use the raw request body, not parsed and re-stringified JSON. After verification, fetch the canonical invoice or withdrawal record before crediting a user, releasing an order, or marking a payout complete.
Webhook note: A valid webhook tells you PayChain sent the event. Your fulfillment system should still fetch the canonical invoice or withdrawal before releasing value.
import { verifyWebhookSignature } from '@paychainhq/sdk';

const verified = verifyWebhookSignature({
  rawBody,
  signature: request.headers['x-webhook-signature'],
  secret: process.env.PAYCHAIN_WEBHOOK_SECRET!
});

if (!verified) {
  throw new Error('Invalid PayChain webhook signature');
}

​
Read balances, transactions, networks, and tokens

Use balances to understand treasury availability, transactions to reconcile invoice and withdrawal activity, networks to discover supported rails, and tokens to confirm which assets can be accepted or withdrawn. See Supported networks and tokens for the current catalog pattern and discovery guidance. Do not treat raw wallet balances as invoice truth. Invoice state and signed webhook events remain the source of truth for customer payments. 
const balances = await paychain.balances.list();
const transactions = await paychain.transactions.list({ limit: 50 });
const networks = await paychain.networks.list();
const tokens = await paychain.tokens.list();

​
Do not do this

  • Do not ship API keys to browsers or mobile apps.
  • Do not log SDK config, request headers, API keys, webhook secrets, or payout destination auth tokens.
  • Do not disable webhook verification.
  • Do not use standard API keys for withdrawals.
  • Do not trust client-submitted payout destinations without your own validation.