Payments

Read payment records for your business. Payments are created automatically when a client pays an invoice through EsperWorks. Use webhooks to be notified in real time.

Endpoints

GEThttps://api.tryesperworks.com/api/v1/paymentspayments:read

List payments. Supports ?status=, ?per_page=.

POSThttps://api.tryesperworks.com/api/v1/invoices/:id/initiate-paymentinvoices:write

Get the payment URL for an invoice. Returns simulate_url in test mode.

POSThttps://api.tryesperworks.com/api/v1/invoices/:id/simulate-paymentinvoices:write

Test mode only, simulate a successful payment and fire webhooks.

List payments

curl "https://api.tryesperworks.com/api/v1/payments?status=success" \
  -H "Authorization: Bearer ew_live_xxxx"

Response

{
  "data": [
    {
      "id": 55,
      "amount": 3000,
      "currency": "GHS",
      "status": "success",
      "gateway": "paystack",
      "reference": "pay_xxxxxxxxxxxx",
      "paid_at": "2026-05-01T14:22:00Z",
      "invoice": { "id": 101, "invoice_number": "INV-0042" },
      "client": { "id": 42, "name": "Kofi Mensah" }
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 20, "total": 1 }
}

Simulate a payment (test mode)

Only available with ew_test_ keys. Marks the invoice paid and fires payment.received and invoice.paid webhooks to your endpoint, so you can test your webhook handler without a real transaction.

curl -X POST https://api.tryesperworks.com/api/v1/invoices/101/simulate-payment \
  -H "Authorization: Bearer ew_test_xxxx"

Payment statuses

Status	Description
`success`	Payment confirmed and settled.
`pending`	Initiated but not yet confirmed by the gateway.
`failed`	Payment attempt failed.
`refunded`	Payment was refunded.

Payment gateways

The gateway field indicates which payment processor handled the transaction (internal implementation detail): paystack, flutterwave, or hubtel. EsperWorks automatically routes to the appropriate processor based on the client's country and payment channel (card or mobile money).