SDK Guide

The PayChain SDK is the recommended integration path for Node.js and TypeScript backends. It wraps the same public REST API with typed helpers, safer payout split handling, idempotency support, error mapping, and webhook verification utilities.

Positioning note: Use the SDK when your backend runs Node.js or TypeScript. Use the REST API directly when you need another language, full HTTP control, or your own wrapper.

Install

npm install @paychainhq/sdk

Create a client

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

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

What the SDK covers

Customers.
Invoices.
Payout route attachment.
Dynamic payout recipients.
Withdrawals.
Webhooks.
Balances.
Transactions.
Networks.
Tokens.

What the SDK does not cover

Account settings, API key management, billing changes, and payout-route administration that are handled in the dashboard.
Unsupported or private beta surfaces that are not part of the public API.
Low-level custody, infrastructure, or treasury implementation details.

Security note: The SDK is server-side only. Do not bundle it into browser or mobile apps with API keys.

Idempotency

Every mutating operation should include an idempotency key.

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

Customer deposit addresses

For reusable customer deposit-address flows, ensure the customer has an address for the rail before showing payment instructions. ensureAddress returns an existing address when one already exists, or creates a missing address when the business is configured for the requested rail. Call it before displaying a reusable address, not only during customer creation. This lets existing customers receive newly supported rail addresses as PayChain adds networks over time.

Solana

const solanaAddress = await paychain.customers.ensureAddress(
  'customer_123',
  {
    chain: 'sol',
    networkId: 'sol-mainnet'
  },
  { idempotencyKey: 'customer_123_sol_address' }
);

if (
  solanaAddress.address.chainFamily !== 'sol' ||
  solanaAddress.address.networkId !== 'sol-mainnet'
) {
  throw new Error('Solana deposit address is not available for this customer');
}

console.log(solanaAddress.address.address);

Stellar dedicated addresses

const stellarAddress = await paychain.customers.ensureAddress(
  'customer_123',
  {
    chain: 'stellar',
    networkId: 'stellar-mainnet',
    token: 'XLM'
  },
  { idempotencyKey: 'customer_123_stellar_address' }
);

if (
  stellarAddress.address.chainFamily !== 'stellar' ||
  stellarAddress.address.networkId !== 'stellar-mainnet'
) {
  throw new Error('Stellar deposit address is not available for this customer');
}

console.log(stellarAddress.address.address);

Most Stellar invoice and Auto Deposit Intent integrations do not need ensureAddress. By default, PayChain returns the business Stellar treasury address plus a required Memo ID:

const invoice = await paychain.invoices.create({
  amount: '5',
  token: 'USDC',
  chain: 'stellar',
  networkId: 'stellar-mainnet',
  assetCode: 'USDC',
  issuerAddress: 'GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
  canonicalAssetId: 'stellar:USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN'
});

console.log(invoice.depositAddress);
console.log(invoice.memo?.value);

Address selection note: Non-EVM reusable-address flows must use the address returned for the requested rail, such as chainFamily: "sol" with networkId: "sol-mainnet" or, when explicitly using Stellar dedicated addresses, chainFamily: "stellar" with networkId: "stellar-mainnet". Never fall back to ethAddress, the first customer address, or any 0x... address when a Solana or Stellar address is expected.

Lazy provisioning note: PayChain can create a missing customer address for a supported rail on demand. If only one active network matches the requested rail, PayChain may infer networkId, but SDK integrations should pass networkId explicitly for a predictable address-selection pattern.

Invoice confirmation progress

Use invoices.get to poll canonical invoice state while a payment is waiting for required network confirmations.

const invoice = await paychain.invoices.get('invoice_123');

if (invoice.confirmationProgress?.status === 'confirming') {
  console.log({
    current: invoice.confirmationProgress.current,
    required: invoice.confirmationProgress.required,
    remaining: invoice.confirmationProgress.remaining,
    percent: invoice.confirmationProgress.percent,
    txHash: invoice.confirmationProgress.txHash
  });
}

Fulfillment note: Wait for paid or overpaid invoice status before fulfilling. Confirmation progress is for customer-facing visibility while settlement finality is still pending.

Webhook verification

Webhook verification must use the raw request body.

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');
}

Raw body note: Do not parse and re-stringify JSON before verifying. Use the exact bytes PayChain sent.

When to use REST instead

Use REST directly when:

Your backend is not Node.js or TypeScript.
You need language-specific HTTP instrumentation.
You want to build your own wrapper.
You need to inspect exact request and response payloads.
You are debugging endpoint-level behavior.

Start here

Developers

Go live

Sdk guide

SDK Guide

Install

Create a client

What the SDK covers

What the SDK does not cover

Idempotency

Customer deposit addresses

Solana

Stellar dedicated addresses

Invoice confirmation progress

Webhook verification

When to use REST instead

​SDK Guide

​Install

​Create a client

​What the SDK covers

​What the SDK does not cover

​Idempotency

​Customer deposit addresses

​Solana

​Stellar dedicated addresses

​Invoice confirmation progress

​Webhook verification

​When to use REST instead

SDK Guide

Install

Create a client

What the SDK covers

What the SDK does not cover

Idempotency

Customer deposit addresses

Solana

Stellar dedicated addresses

Invoice confirmation progress

Webhook verification

When to use REST instead