Invoices

​

Overview

​

Authentication

• x-api-key: <merchant_api_key>, or
• Authorization: Bearer <jwt>

​

Request

• 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)

• GET /api/v1/payments/payment-status
• POST /api/v1/invoice/{invoiceId}/verify
• GET /api/v1/invoice/{invoiceId}/verify

• Create an invoice
• List invoices
• Retrieve an invoice
• Get invoice status

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","expires_in":43200000}'

• expires_in is milliseconds (default 12 hours, max 30 days).

​

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_..."
  }
}

​

Errors

• 401/403 missing/invalid auth
• 400 invalid invoice payload
• 429 rate limits

{
  "success": false,
  "error": { "code": "VALIDATION_ERROR", "message": "Invalid request data" }
}

​

Examples

• 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