Skip to main content

​
Overview

Invoices are the primary merchant payment object in Pepay.

​
Authentication

Merchant invoices typically use:
  • x-api-key (recommended for server-to-server), or
  • Authorization: Bearer <jwt> (dashboard session)

​
Request

​
Create an invoice

const pepay = new Pepay({ apiKey: process.env.PEPAY_API_KEY! });

const invoice = await pepay.invoices.create({
  amount_usd: 49.99,
  description: 'Starter plan',
  expires_in: 12 * 60 * 60 * 1000
});
Notes:
  • expires_in is milliseconds (default 12 hours, max 30 days).

​
List invoices (cursor pagination + filters)

const list = await pepay.invoices.list({
  limit: 10,
  status: 'paid',
  invoice_type: 'standard',
  environment: 'mainnet'
});

​
Receipt lookup by payer wallet

const receipts = await pepay.invoices.list({
  payer_wallet_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f6ce3c',
  payer_wallet_network: 'base',
  status: 'paid',
  expand: 'latest_payment'
});

​
Retrieve invoice details

const invoice = await pepay.invoices.retrieve('inv_123', { expand: 'latest_payment,payments' });

​
Poll status

const status = await pepay.invoices.status('inv_123');

​
Wait for terminal status

const final = await pepay.invoices.waitForStatus('inv_123', {
  timeoutMs: 5 * 60 * 1000,
  intervalMs: 2000
});

​
Response

Create invoice response: 
{
  "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
  "payment_url": "https://<payment-iframe-host>/pay?session=pst_...&signature=sig_...",
  "expires_at": 1766322000,
  "session_token": "pst_...",
  "signature": "sig_...",
  "payment_session_headers": {
    "x-session-token": "pst_...",
    "x-signature": "sig_..."
  }
}
Invoice status response (polling): 
{
  "object": "invoice_status",
  "invoice": { "object": "invoice", "id": "550e8400-e29b-41d4-a716-446655440000", "status": "paid" },
  "latest_payment": {
    "object": "invoice_payment",
    "status": "confirmed",
    "settlement_status": "settled",
    "settlement": {
      "summary_status": "settled",
      "stage": "final",
      "merchant_settlement_id": 30,
      "settlement_tx_hash": "0xabc123",
      "network": "bsc",
      "status": "settled"
    }
  }
}

​
Errors

  • 400 invalid invoice params (create) or invalid cursor/filters (list)
  • 401 missing/invalid merchant auth headers
  • 404 invoice not found (retrieve/status)
  • 409 idempotency conflict on create

​
Examples

Manual verification (payor/session auth): 
await pepay.invoices.manualVerification.trigger(invoiceId, { network: 'base' });
const job = await pepay.invoices.manualVerification.status(invoiceId);
Next: Tokens