Webhooks

When a payment is received on a Kler collection account, Kler fires a POST request to the webhook_url you set when creating the session.

Event types

Event	When it fires
`transaction.received`	A payment has been recorded on the session

More event types (e.g. session.closed, terminal.offline) will be added over time.

Payload

{
  "event": "transaction.received",
  "session_id": "sess_...",
  "data": {
    "id": "txn_...",
    "amount": "5000.00",
    "currency": "NGN",
    "channel": "bank_transfer",
    "status": "successful",
    "sender_name": "Jane Doe",
    "sender_account": "0123456789",
    "sender_bank": "058",
    "narration": "Ticket purchase",
    "providus_ref": "PVS20250801XXXXXXX",
    "paid_at": "2025-08-01T18:32:00.000Z"
  }
}

Channel values

Value	Meaning
`bank_transfer`	NIP / instant bank transfer
`pos`	POS terminal
`ussd`	USSD payment
`card`	Web/card payment

Handling webhooks

Your endpoint should:

Return a 200 response quickly — Kler does not wait for your processing to complete
Process the event asynchronously if needed
Be idempotent — the same transaction.id may be delivered more than once

app.post('/webhooks/kler', async (req, res) => {
  res.status(200).send({ received: true }) // respond immediately

  const { event, session_id, data } = req.body

  if (event === 'transaction.received') {
    await recordPayment(session_id, data)
  }
})

Retries

If your endpoint does not return a 2xx response, Kler will retry the webhook with exponential backoff up to 5 times.

Get Started

Core Concepts

Event types

Payload

Channel values

Handling webhooks

Retries

​Event types

​Payload

​Channel values

​Handling webhooks

​Retries

Event types

Payload

Channel values

Handling webhooks

Retries