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

​
List invoices (cursor pagination + filters)

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

​
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": "2025-12-21T13:00:00.000Z",
  "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" }
}

​
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