DocsPayments

Payments

Learn how to create and manage crypto payments. Understand the payment lifecycle and handle different scenarios.

How Payments Work

When you create a payment, PayHub generates a unique blockchain address for your customer. The customer sends crypto to this address, and our system monitors the blockchain for incoming transactions.

Create

Pending

Detected

Completed

Create a Payment

Use the payments.create() method to create a new payment:

create-payment.ts

const payment = await client.payments.create({
  // Required
  amount: '100.00',        // Amount in token units
  currency: 'USDC',        // Token symbol
  network: 'polygon',      // Blockchain network

  // Optional
  description: 'Order #12345',
  expiresIn: 3600,         // Expiry time in seconds (default: 1 hour)
  confirmations: 12,       // Required confirmations (default: network-specific)
  metadata: {
    orderId: '12345',
    customerEmail: 'customer@example.com',
  },
  callbackUrl: 'https://your-site.com/webhooks',
  redirectUrl: 'https://your-site.com/thank-you',
});

Response

JSON

{
  "id": "pay_abc123xyz",
  "status": "pending",
  "amount": "100.00",
  "currency": "USDC",
  "network": "polygon",
  "address": "0x1234...abcd",
  "checkoutUrl": "https://checkout.payhub.work/pay_abc123xyz",
  "expiresAt": "2024-01-15T12:00:00Z",
  "createdAt": "2024-01-15T11:00:00Z",
  "metadata": {
    "orderId": "12345"
  }
}

Idempotency

Pass an idempotencyKey to prevent duplicate payments. If you retry a request with the same key, you'll get the original payment instead of creating a new one.

Payment Statuses

Payments go through several statuses during their lifecycle:

pending

Payment created, waiting for customer to send funds

detected

Transaction detected on blockchain, waiting for confirmations

confirming

Transaction is being confirmed

confirmed

Required confirmations reached

completed

Payment fully processed and finalized

expired

Payment expired before receiving funds

underpaid

Received amount is less than expected

overpaid

Received amount is more than expected

Retrieve Payments

Get a single payment by ID or list payments with filters:

TypeScript

// Get a single payment
const payment = await client.payments.get('pay_abc123xyz');

// List all payments
const payments = await client.payments.list({
  limit: 20,
  status: 'completed',
  from: '2024-01-01',
  to: '2024-01-31',
});

Supported Currencies

We support major cryptocurrencies and stablecoins:

ETH

Ethereum

USDC

USD Coin

USDT

Tether

DAI

Dai

MATIC

Polygon

WETH

Wrapped ETH

See Networks for currency availability per blockchain.

Authentication Webhooks