REST API Guide

PayChain exposes the same core payment, payout, balance, transaction, network, token, billing, and webhook surfaces over HTTPS. The SDK is recommended for Node.js and TypeScript, but the REST API remains the source of truth for direct integrations.

API positioning: PayChain is SDK-first for speed, but API-complete for teams that need direct HTTP access or non-TypeScript environments.

For exact schemas, query parameters, and endpoint paths, use OpenAPI reference.

Base URLs

Environment	Base URL
Live	`https://api.paychainhq.io/api/v1`
Sandbox	Use the sandbox API URL provided in your dashboard or onboarding materials.

Environment note: Keep sandbox and live API keys, webhook secrets, and webhook URLs separate.

Required headers

x-api-key: $PAYCHAIN_API_KEY
content-type: application/json
Idempotency-Key: order_123_invoice

Use Idempotency-Key on mutating requests so retries do not create duplicate invoices, withdrawals, or payout actions.

API key types

Key type	Use it for	Do not use it for
Standard API key	Customers, invoices, reads, balances, transactions, networks, tokens, webhooks.	Programmatic withdrawals or fund movement.
Payout API key	Programmatic withdrawals and approved payout automation.	Account administration, billing changes, or broad dashboard access.

Pricing note: A payout API key is necessary for programmatic withdrawal creation, and the request must still pass policy, balance, and destination checks. Free plan businesses have 0 included payout API withdrawals, so the Free payout API fee applies from the first programmatic withdrawal.

Security note: API keys must stay on your backend. Never expose them in frontend JavaScript, mobile apps, public repositories, browser extensions, or analytics logs.

Common REST request pattern

curl -X POST "$PAYCHAIN_API_URL/businesses/$PAYCHAIN_BUSINESS_ID/invoices" \
  -H "x-api-key: $PAYCHAIN_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: order_123_invoice" \
  -d '{
    "amount": "100.00",
    "token": "USDC",
    "chain": "evm",
    "networkId": "base-mainnet",
    "metadata": {
      "orderId": "order_123"
    }
  }'

Core REST examples

Create a customer

curl -X POST "$PAYCHAIN_API_URL/businesses/$PAYCHAIN_BUSINESS_ID/customers" \
  -H "x-api-key: $PAYCHAIN_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: customer_123_create" \
  -d '{
    "externalRef": "customer_123"
  }'

Ensure a customer deposit address

Use this before displaying a reusable customer address for a specific rail. Send the exact chain and networkId, then verify the returned address.chainFamily and address.networkId before showing the address to the payer. Solana and Stellar use the same ensure pattern: call the customer address ensure endpoint for the exact rail and never fall back to an EVM 0x... address when a non-EVM address is expected. The ensure endpoint:

Returns the existing customer address when the customer already has one for the requested rail.
Provisions a missing address when the business is configured for that rail.
Returns created and address metadata so your backend can verify the rail before displaying payment instructions.

Call this endpoint before showing a reusable address, not only when the customer is first created. This keeps existing customers compatible when PayChain enables a new network, because older customers may not have an address for that rail until your integration asks PayChain to ensure it.

curl -X POST "$PAYCHAIN_API_URL/businesses/$PAYCHAIN_BUSINESS_ID/customers/$CUSTOMER_ID/addresses/ensure" \
  -H "x-api-key: $PAYCHAIN_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: customer_123_sol_address" \
  -d '{
    "chain": "sol",
    "networkId": "sol-mainnet"
  }'

curl -X POST "$PAYCHAIN_API_URL/businesses/$PAYCHAIN_BUSINESS_ID/customers/$CUSTOMER_ID/addresses/ensure" \
  -H "x-api-key: $PAYCHAIN_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: customer_123_stellar_address" \
  -d '{
    "chain": "stellar",
    "networkId": "stellar-mainnet",
    "token": "XLM"
  }'

The response returns created: true when PayChain provisioned a new address, or created: false when the address already existed. Use the returned address.address only when the returned rail matches the requested rail, such as address.chainFamily: "sol" with address.networkId: "sol-mainnet" or address.chainFamily: "stellar" with address.networkId: "stellar-mainnet".

Lazy provisioning note: If networkId is omitted and only one active network matches the requested rail, PayChain may infer it. Production integrations should still send networkId explicitly so the address-selection pattern stays consistent across Solana, Stellar, and future rails.

Get an invoice after a webhook

curl "$PAYCHAIN_API_URL/businesses/invoices/inv_123" \
  -H "x-api-key: $PAYCHAIN_API_KEY"

Poll invoice confirmation progress

curl "$PAYCHAIN_API_URL/invoices/inv_123" \
  -H "x-api-key: $PAYCHAIN_API_KEY"

When a payment is waiting for finality, invoice responses can include confirmationProgress.current, confirmationProgress.required, confirmationProgress.remaining, confirmationProgress.percent, and confirmationProgress.txHash.

List invoices for reconciliation

curl "$PAYCHAIN_API_URL/businesses/$PAYCHAIN_BUSINESS_ID/invoices?status=paid&limit=50" \
  -H "x-api-key: $PAYCHAIN_API_KEY"

Quote and create a withdrawal

curl -X POST "$PAYCHAIN_API_URL/businesses/$PAYCHAIN_BUSINESS_ID/withdrawals/quote" \
  -H "x-api-key: $PAYCHAIN_PAYOUT_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: payout_123_quote" \
  -d '{
    "amount": "25.00",
    "token": "USDC",
    "chain": "evm",
    "networkId": "base-mainnet",
    "destinationAddress": "0x0000000000000000000000000000000000000000"
  }'

curl -X POST "$PAYCHAIN_API_URL/businesses/$PAYCHAIN_BUSINESS_ID/withdrawals" \
  -H "x-api-key: $PAYCHAIN_PAYOUT_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: payout_123_create" \
  -d '{
    "quoteId": "quote_123",
    "clientReference": "payout_123"
  }'

Read balances and transactions

curl "$PAYCHAIN_API_URL/businesses/$PAYCHAIN_BUSINESS_ID/balances" \
  -H "x-api-key: $PAYCHAIN_API_KEY"

curl "$PAYCHAIN_API_URL/businesses/$PAYCHAIN_BUSINESS_ID/transactions?limit=50" \
  -H "x-api-key: $PAYCHAIN_API_KEY"

Balance responses separate amounts.total from amounts.totalHeld and amounts.requiresRecovery. Use amounts.total or withdrawal quotes for payout capacity.

Discover networks and tokens

curl "$PAYCHAIN_API_URL/networks" \
  -H "x-api-key: $PAYCHAIN_API_KEY"

curl "$PAYCHAIN_API_URL/tokens?networkId=base-mainnet" \
  -H "x-api-key: $PAYCHAIN_API_KEY"

Read billing and gas usage

curl "$PAYCHAIN_API_URL/billing/me" \
  -H "x-api-key: $PAYCHAIN_API_KEY"

curl "$PAYCHAIN_API_URL/billing/usage" \
  -H "x-api-key: $PAYCHAIN_API_KEY"

Response handling

Store these values when available:

PayChain resource ID.
Your own clientReference or externalRef.
x-request-id.
Status.
Amount, token, chain, and network.
Webhook delivery ID.
Transaction hash after settlement or payout completion.

Pagination

List endpoints may paginate. Keep pagination handling server-side and do not build business-critical reconciliation from a small client-side row limit.

Errors

Expect structured errors with:

HTTP status.
Machine-readable code.
Message.
Request ID.
Details where available.

Error handling note: Do not retry validation errors, authentication errors, or policy rejections blindly. Retry only transient network failures, 408, 429, and 5xx responses, and only retry non-idempotent POST requests when an idempotency key is present.

Webhooks

REST integrations should still use signed webhooks for real-time lifecycle changes.

X-Webhook-Signature: ...
X-Webhook-Timestamp: ...
X-Webhook-ID: ...

Verify the signature with the raw request body, then fetch the canonical invoice or withdrawal before fulfillment. See Webhooks for event handling, retries, replay, and common mistakes.

How REST maps to the SDK

SDK method	REST concept
`paychain.customers.create()`	Create customer endpoint
`paychain.invoices.create()`	Create invoice endpoint
`paychain.invoices.get()`	Get invoice endpoint
`paychain.withdrawals.quote()`	Quote withdrawal endpoint
`paychain.withdrawals.create()`	Create withdrawal endpoint
`paychain.balances.list()`	List balances endpoint
`paychain.transactions.list()`	List transactions endpoint
`paychain.networks.list()`	List supported networks endpoint
`paychain.tokens.list()`	List supported tokens endpoint

See Supported networks and tokens before hardcoding any network or token assumptions.

Production checklist

API keys stored in protected server-side secret storage.
Idempotency keys on mutating requests.
Webhook signature verification uses raw body.
Standard and payout API keys are separated.
Request IDs are logged without secrets.
Sandbox and live credentials are separate.
Payout destinations are validated server-side.
Billing, gas credits, and payout quota behavior are understood.

Start here

Developers

Go live

Rest api guide

REST API Guide

Base URLs

Required headers

API key types

Common REST request pattern

Core REST examples

Create a customer

Ensure a customer deposit address

Get an invoice after a webhook

Poll invoice confirmation progress

List invoices for reconciliation

Quote and create a withdrawal

Read balances and transactions

Discover networks and tokens

Read billing and gas usage

Response handling

Errors

Webhooks

How REST maps to the SDK

Production checklist

​REST API Guide

​Base URLs

​Required headers

​API key types

​Common REST request pattern

​Core REST examples

​Create a customer

​Ensure a customer deposit address

​Get an invoice after a webhook

​Poll invoice confirmation progress

​List invoices for reconciliation

​Quote and create a withdrawal

​Read balances and transactions

​Discover networks and tokens

​Read billing and gas usage

​Response handling

​Pagination

​Errors

​Webhooks

​How REST maps to the SDK

​Production checklist

REST API Guide

Base URLs

Required headers

API key types

Common REST request pattern

Core REST examples

Create a customer

Ensure a customer deposit address

Get an invoice after a webhook

Poll invoice confirmation progress

List invoices for reconciliation

Quote and create a withdrawal

Read balances and transactions

Discover networks and tokens

Read billing and gas usage

Response handling

Pagination

Errors

Webhooks

How REST maps to the SDK

Production checklist