Webhooks

Listen for webhook events on the URL configured in your merchant settings. Kora sends two categories of events related to direct debit:

Authorization events – the customer's authorization approval succeeded or failed.
Debit (collection) events – an individual debit attempt completed.

Authorization Events – `direct_debit.auth`

This event fires whenever the customer's authorization transitions from pending to either active (success) or deactivated (failure). It is the only signal you need to start debiting a variable authorization.

Event Type	Status	Meaning
`direct_debit.auth`	`success`	Bank approved the authorization. It is now `active` and immediately ready to debit.
`direct_debit.auth`	`failed`	Bank rejected the authorization. It will not become active.

Sample payload — success ("direct‑debit‑auth.success")

{
  "type": "direct_debit.auth",
  "status": "success",
  "data": {
    "reference": "KPY-AUTH-7d2f9c0e",
    "authorization_code": "KPY-AUTH-7d2f9c0e",
    "amount": 500000,
    "currency": "NGN",
    "authorization_type": "variable",
    "start_date": "2026-04-01T00:00:00.000Z",
    "end_date": "2026-12-31T00:00:00.000Z",
    "status": "success",
    "date": "2026-04-19T10:25:40.001Z",
    "customer_account": {
      "account_number": "0123456789",
      "account_name": "JANE ADAEZE DOE",
      "bank_code": "044"
    },
  }
}

Sample payload — failed

{
  "type": "direct_debit.auth",
  "status": "failed",
  "data": {
    "reference": "KPY-AUTH-7d2f9c0e",
    "authorization_code": "KPY-AUTH-7d2f9c0e",
    "amount": 500000,
    "currency": "NGN",
    "authorization_type": "variable",
    "start_date": "2026-04-01T00:00:00.000Z",
    "end_date": "2026-12-31T00:00:00.000Z",
    "status": "failed",
    "date": "2026-04-19T10:25:40.001Z",
    "customer_account": {
      "account_number": "0123456789",
      "account_name": "JANE ADAEZE DOE",
      "bank_code": "044"
    }
  }
}

Debit Outcome Events – `charge.success / charge.failed`

When a debit (variable or scheduled fixed) finishes, Kora sends the standard collection webhook (charge.success or charge.failed). It carries a nested direct_debit object so you can correlate it to the authorization.

Sample payload: debit success

{
  "event": "charge.success",
  "data": {
    "fee": 12.69,
    "payment_reference": "KPY-PAY-LvfGxDsjOW6Ke83",
    "amount": 100,
    "currency": "NGN",
    "reference": "KPY-PAY-LvfGxDsjOW6Ke83",
    "payment_method": "direct_debit",
    "status": "success",
    "direct_debit": {
      "authorization_code": "KPY-AUTH-VJCT7BSSSCALR6F",
      "account_number": "0112345678",
      "account_name": "vee Test",
      "bank_code": "058"
    }
  }
}

Sample payload — debit failed

{
  "event": "charge.failed",
  "data": {
    "fee": 12.69,
    "payment_reference": "KPY-PAY-LvfGxDsjOW6Ke83",
    "amount": 100,
    "currency": "NGN",
    "reference": "KPY-PAY-LvfGxDsjOW6Ke83",
    "payment_method": "direct_debit",
    "status": "failed",
    "direct_debit": {
      "authorization_code": "KPY-AUTH-VJCT7BSSSCALR6F",
      "account_number": "0112345678",
      "account_name": "vee Test",
      "bank_code": "058"
    }
  }
}

Event Summary

Event	Description
`direct_debit.auth (status: success)`	Authorization activated by the bank, ready to debit.
`direct_debit.auth (status: failed)`	Authorization rejected by the bank.
`charge.success (with channel: direct_debit)`	A direct debit was successfully completed.
`charge.failed (with channel: direct_debit)`	A direct debit attempt failed.

Status Reference

Authorization Status

Status	Meaning
`pending`	Created but the customer has not completed NIBSS approval.
`active`	Approved by the bank and ready to debit.
`suspended`	Temporarily paused. Debits are blocked.
`deactivated`	Permanently disabled (by merchant, admin, or bank rejection).
`expired`	Past `end_date`.

Debit (Transaction) Status

Status	Meaning
`pending`	Submitted to NIBSS, awaiting initial response.
`processing`	Accepted, being processed at the bank.
`success`	Funds were debited from the customer's account.
`failed`	The debit attempt was rejected.

Authorization Type

Type	Meaning
`variable`	You trigger each debit manually via the API.
`fixed`	Kora runs scheduled debits automatically based on `frequency / interval.`

Frequency Values (fixed authorizations only)

The available frequency options are: weekly, biweekly, monthly, bimonthly, quarterly, semi-annually, and yearly. Alternatively, you can use days, weeks, or months. When using these time units, the interval field must be specified (e.g., setting frequency to "days" and interval to 14 means the action will occur every 14 days).

Common Error Codes

Code	HTTP	Meaning
`validation_error`	422	Request body / params failed schema validation.
`bad_request`	400	Malformed request.
`not_authenticated`	401	Missing or invalid `Authorization` header / secret key.
`not_authorized`	403	Merchant not permitted (e.g. live mode not enabled, direct debit channel disabled, authorization not in `active` state, amount outside transaction limits).
`not_found`	404	Authorization (`reference` / `authorization_code`) does not exist for this merchant.
`conflict`	409	Customer account name enquiry failed at the bank.
`server_error`	500	Unexpected error on Kora's side.

Authorization Events – direct_debit.auth

Debit Outcome Events – charge.success / charge.failed