Skip to main content

​
Overview

This page documents the merchant invoice contract used by pepay.

​
Authentication

Merchant invoice APIs accept either:
  • x-api-key: <merchant_api_key>, or
  • Authorization: Bearer <jwt>

​
Request

Endpoints (SDK-supported):
  • POST /api/v1/invoices (create)
  • GET /api/v1/invoices (list)
  • GET /api/v1/invoices/customer/{customerId} (list by customer)
  • GET /api/v1/invoices/{invoiceId} (retrieve)
  • GET /api/v1/invoices/{invoiceId}/status (status)
  • GET /api/v1/invoices/totals (totals)
Payor/session helpers (browser-safe auth):
  • GET /api/v1/payments/payment-status
  • POST /api/v1/invoice/{invoiceId}/verify
  • GET /api/v1/invoice/{invoiceId}/verify
Playground (interactive reference): Example (create invoice): 
BASE_URL=${PEPAY_API_URL}

curl -X POST "$BASE_URL/api/v1/invoices" \
  -H "x-api-key: sk_live_..." \
  -H "Idempotency-Key: 123e4567-e89b-42d3-a456-556642440000" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd":49.99,"description":"Starter plan"}'

​
Response

Example response (create): 
{
  "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_..."
  }
}

​
Errors

  • 401/403 missing/invalid auth
  • 400 invalid invoice payload
  • 429 rate limits
Example (invalid payload): 
{
  "success": false,
  "error": { "code": "VALIDATION_ERROR", "message": "Invalid request data" }
}

​
Examples

Pagination + status semantics:
  • List endpoints use cursor pagination (see Pagination).
  • Common status fields:
    • Invoice status: unpaid, underpaid, paid, expired, canceled
    • Payment receipt status: pending, underpaid, confirmed, manual_retry
    • Settlement status (merchant-safe): pending, processing, manual, failed, settled
Next: Events