Webhook Events - Daya API Documentation

Overview

Daya sends merchant webhooks for funding account, deposit, transfer, withdrawal, customer verification, and customer bank-account verification lifecycle changes. Every webhook uses the same envelope:

{
  "event": "transfer.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "id": "650e8400-e29b-41d4-a716-446655440000",
    "status": "SETTLED",
    "rail": "NGN_BANK"
  },
  "timestamp": "2026-03-10T09:03:00Z"
}

event tells you what changed, id identifies the webhook event for idempotency, and data describes the resource or verification result that changed.

Common Payload Fields

string

Event type for the lifecycle transition that occurred.

string

Unique webhook event identifier. Use this value for idempotency.

object

Payload for the event. Resource lifecycle events follow the corresponding public API response, while bank-account verification events use the result shape documented below.

string

RFC3339 timestamp for when the event was emitted.

Data Shapes

Webhook events are documented here at the event-name level. Resource lifecycle events use the corresponding public API response object; bank-account verification events use the result object documented on this page.

Event family	`data` shape	Resource docs
`funding_account.*`	Funding account response object	Get Funding Account
`deposit.*`	Deposit response object	Get Deposit, or Get USD Account Deposit when `type` is `USD_DEPOSIT`
`transfer.*`	Transfer response object	Get Transfer
`withdrawal.*`	Withdrawal response object	Get Withdrawal
`customer.verification.*`	Customer response object with the latest verification state	Get Customer
`customer.bank_account_verification.*`	Bank-account verification result with customer, provider, and identity version	Bank Account Verification Events

For resource lifecycle events, fetch the latest resource by the id in data when needed. Bank-account verification events identify the customer with data.customer_id.Check data.type before refetching a deposit: GET /v1/deposits/{id} returns 404 for a USD_DEPOSIT, which use GET /v1/virtual-account-deposits/{id} instead.

Deposit Events

Event	Terminal?	When Sent
`deposit.received`	No	Deposit received (NGN, crypto, or USD)
`deposit.processing`	No	Settlement has started and may be waiting on conversion or delivery
`deposit.requires_review`	No	Deposit needs review before it can continue
`deposit.completed`	Yes	Deposit reached its settlement destination
`deposit.failed`	Yes	Deposit permanently fails
`deposit.reversed`	Yes	A completed deposit was reversed

Credit on deposit.completed, on every rail. It is the only deposit event that means the money is final. Never credit on deposit.received, on any rail. For NGN and crypto the deposit can still move to deposit.requires_review or deposit.failed afterwards. For USD virtual account deposits the money is already settled when deposit.received is sent — so its payload reports "status": "COMPLETED" — but deposit.completed is sent for the same deposit moments later, and crediting on both pays twice. See USD Virtual Account Deposit. Deposit payloads for NGN and crypto receive flows include funding_account_id. When a developer fee is configured, deposit payloads include developer_fee and customer_amount. The developer fee is deducted before the final customer amount is calculated; it is not added as a separate charge. Track the merchant-facing settlement lifecycle with deposit.* events.

Funding Account Events

Funding account events track receive-instruction provisioning and disablement. The data object is the public funding account response.

Event	Terminal?	When Sent
`funding_account.created`	No	Funding account record has been created in `PENDING` status
`funding_account.active`	No	Payment details are ready and the account is active
`funding_account.updated`	No	A funding-account instruction changed status or received updated payment details
`funding_account.failed`	Yes	Receive instruction provisioning failed
`funding_account.disabled`	Yes	Active funding account was disabled

Transfer Events

Transfer events are emitted for POST /v1/transfers and follow the merchant-created transfer lifecycle.

Event	Terminal?	When Sent
`transfer.created`	No	Transfer record and initial attempt have been created
`transfer.processing`	No	Funds have been locked and provider submission has been queued
`transfer.requires_review`	No	Risk or ops policy flagged the transfer for review
`transfer.submitted`	No	Provider accepted the transfer submission
`transfer.completed`	Yes	Provider success and ledger finalization are complete
`transfer.failed`	Yes	Transfer failed terminally after release or failure reconciliation
`transfer.reversed`	Yes	A previously completed transfer was reversed

Withdrawal Events

Event	Terminal?	When Sent
`withdrawal.created`	No	Withdrawal request has been accepted
`withdrawal.submitted`	No	Withdrawal submitted to chain
`withdrawal.completed`	Yes	Withdrawal confirmed on-chain
`withdrawal.failed`	Yes	Withdrawal failed

Customer Verification Events

Event	Terminal?	When Sent
`customer.verification.submitted`	No	Customer verification has been submitted for review
`customer.verification.approved`	Yes	Customer verification has been approved
`customer.verification.information_requested`	No	More information is required to continue customer verification
`customer.verification.rejected`	Yes	Customer verification has been rejected

Customer Bank Account Verification Events

These events report Paystack’s asynchronous verification result for the bank details submitted through Tier 1 KYC. They do not change the customer’s Tier 1 KYC status.

Event	Terminal?	When Sent
`customer.bank_account_verification.succeeded`	Yes	Paystack verified the customer’s current bank-account identity
`customer.bank_account_verification.failed`	Yes	Paystack rejected the customer’s current bank-account identity

Both events include customer_id, provider, status, and identity_version. A failed event also includes failure_code and failure_message. When the customer submits new bank details, Daya increments identity_version; ignore an older result after you have received a result for a newer version.

All event families use the same webhook envelope and top-level id for delivery deduplication. Funding account payloads use the public funding account response shape.

Bank Account Verification Events

When you include bank_account and the required phone_number in a Tier 1 verification request, Daya resolves and stores the bank details, then starts Paystack’s asynchronous bank account verification. If Paystack is temporarily unavailable, Daya keeps the verification pending and starts it automatically after the provider recovers. The Tier 1 API response confirms that the submission was accepted; receive the Paystack result through one of these events:

Event	Terminal?	When Sent
`customer.bank_account_verification.succeeded`	No	Paystack currently reports the submitted bank details as verified
`customer.bank_account_verification.failed`	No	Paystack currently reports the submitted bank details as not verified

The data object contains:

Field	Type	Description
`customer_id`	string	Customer whose bank details were checked
`provider`	string	Verification provider; currently `PAYSTACK`
`status`	string	`VERIFIED` for success or `FAILED` for failure
`identity_version`	integer	Version of the customer’s submitted bank details
`failure_code`	string	Stable failure category; included only when verification fails
`failure_message`	string	Explanation of the failure; included only when verification fails

Bank detail updates increment identity_version. Daya checks Paystack’s current customer state whenever it processes a signed identification callback, so a later result can supersede an earlier result for the same version. If results arrive out of order, prefer the highest identity_version; for two results with the same version, keep the one with the later timestamp. Deduplicate repeated delivery of the same event with the top-level id. On failure, use failure_code and failure_message to tell the customer what to correct, then submit the corrected bank details with PATCH /v1/customers/{id}/tier1-verification. On success, Daya can create the Paystack instruction. If the customer already has a permanent NGN funding account, Daya sends funding_account.active when Paystack makes a pending account usable, or funding_account.updated when another instruction was already active. Use the Paystack instruction only after its status is ACTIVE. If the customer does not yet have an account, Daya retains the successful verification and uses it when you create the permanent NGN funding account later.

Lifecycle Examples

These examples show how webhook names follow the public resource being reconciled.

Funding Account Deposit

When a customer sends NGN to a funding account’s virtual account, the incoming money is a deposit. The payment detail is the funding account; the money movement is tracked with deposit.* events.

Step	Event	Notes
Funds arrive	`deposit.received`	Daya records the NGN deposit.
Settlement starts	`deposit.processing`	Sent when delivery or conversion work begins.
Deposit completes	`deposit.completed`	Funds have reached the configured settlement destination.
Review or failure path	`deposit.requires_review` or `deposit.failed`	Sent if the deposit cannot proceed automatically.

USD Virtual Account Deposit

When a customer sends USD to a virtual account, the deposit is received and settled in a single step. Both events are sent at the same moment and no deposit.processing is sent.

Step	Event	Notes
Funds arrive and settle	`deposit.received`	Daya records the USD deposit. Already settled, so `status` is `COMPLETED`. Do not credit here.
Deposit completes	`deposit.completed`	Sent at the same moment. Credit here.

Because the two events are delivered independently, they can arrive in either order. Treat deposit.completed as the signal to credit, and make your handler tolerant of it arriving before deposit.received.

Credit exactly once per deposit. Because a USD deposit is already settled when deposit.received is sent, every event for it — deposit.received, deposit.completed, and the legacy deposit.settled — carries the same payload with "status": "COMPLETED".A handler that credits whenever data.status == "COMPLETED", without checking the event name, will credit the same deposit three times. Either credit only on deposit.completed (treating deposit.settled as the same event), or make crediting idempotent on data.id.Deduplicate on data.id, not on the envelope id. Each event gets its own envelope id, so the three events for one deposit have three different envelope ids and the same data.id. Deduplicating on the envelope id will not prevent a double credit.This does not apply to NGN and crypto deposits, where deposit.received carries a non-terminal status and only the terminal event reports COMPLETED.

An endpoint registered with an empty event_types receives every event, so it will receive all three. USD virtual account deposits carry "type": "USD_DEPOSIT" and do not include funding_account_id. They are not served by the /v1/deposits endpoints:

List them with GET /v1/virtual-account-deposits.
Refetch one with GET /v1/virtual-account-deposits/{id}.

GET /v1/deposits/{id} returns 404 for a USD deposit id, so a handler that refetches every deposit through /v1/deposits after a webhook will treat a valid USD deposit as missing. Branch on data.type before refetching.

Internal Balance to NGN Bank Transfer

When a merchant sends withdrawal balance to an NGN bank account through POST /v1/transfers, the public resource is a transfer.

Step	Event	Notes
Request accepted	`transfer.created`	Transfer record and initial attempt exist.
Funds locked	`transfer.processing`	Funds are held and provider submission is queued.
Manual review, if needed	`transfer.requires_review`	Risk or ops policy paused the transfer.
Provider accepts submission	`transfer.submitted`	Provider accepted the transfer request.
Final success	`transfer.completed`	Provider success and ledger finalization are complete.
Final failure	`transfer.failed`	Transfer failed terminally after release or failure reconciliation.

Crypto Wallet Withdrawal

When a merchant sends stablecoin or crypto from the withdrawal balance to an on-chain wallet, the public resource is a withdrawal.

Step	Event	Notes
Request accepted	`withdrawal.created`	Withdrawal record exists.
On-chain transaction submitted	`withdrawal.submitted`	Daya submitted the withdrawal to the chain/provider.
On-chain transaction confirmed	`withdrawal.completed`	Withdrawal is confirmed and complete.
Final failure	`withdrawal.failed`	Withdrawal failed terminally.

Payload Examples

These examples are intentionally representative. The full data object follows the linked resource response shape for each event family.

Funding Account Active

{
  "event": "funding_account.active",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "object": "funding_account",
    "id": "750e8400-e29b-41d4-a716-446655440000",
    "type": "PERMANENT",
    "status": "ACTIVE",
    "rail": "NGN_VIRTUAL_ACCOUNT",
    "customer_id": "650e8400-e29b-41d4-a716-446655440000",
    "currency": "NGN",
    "developer_fee": {
      "percentage": "2.5"
    },
    "settlement_destination": {
      "type": "INTERNAL_BALANCE"
    },
    "instructions": [
      {
        "type": "NGN_VIRTUAL_ACCOUNT",
        "provider": "FLUTTERWAVE",
        "provider_availability": {
          "status": "OPERATIONAL"
        },
        "status": "ACTIVE",
        "bank_name": "Wema Bank",
        "bank_code": "035",
        "account_number": "1234567890",
        "account_name": "Daya - Ada Lovelace",
        "currency": "NGN",
        "required_fields": [],
        "failure": null
      },
      {
        "type": "NGN_VIRTUAL_ACCOUNT",
        "provider": "PAYSTACK",
        "provider_availability": {
          "status": "OPERATIONAL"
        },
        "status": "PENDING",
        "currency": "NGN",
        "required_fields": [],
        "failure": null
      }
    ],
    "created_at": "2026-01-05T15:04:05Z",
    "updated_at": "2026-01-05T15:04:10Z"
  },
  "timestamp": "2026-01-05T15:04:10Z"
}

Deposit Completed

{
  "event": "deposit.completed",
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "data": {
    "type": "CRYPTO_DEPOSIT",
    "id": "850e8400-e29b-41d4-a716-446655440000",
    "funding_account_id": "750e8400-e29b-41d4-a716-446655440000",
    "customer_id": "650e8400-e29b-41d4-a716-446655440000",
    "amount": "12.50",
    "currency": "USDC",
    "status": "COMPLETED",
    "settlement_status": "COMPLETED",
    "settlement_mode": "NGN_PAYOUT",
    "asset": "USDC",
    "chain": "BASE",
    "fees": {
      "total_fee_usd": "0.0500"
    },
    "developer_fee": {
      "percentage": "10",
      "amount": "1.25",
      "currency": "USD"
    },
    "customer_amount": {
      "amount": "16800.00",
      "currency": "NGN"
    },
    "created_at": "2026-01-05T15:04:05Z",
    "updated_at": "2026-01-05T15:04:10Z"
  },
  "timestamp": "2026-01-05T15:04:10Z"
}

Transfer Completed

{
  "event": "transfer.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "id": "850e8400-e29b-41d4-a716-446655440000",
    "reference": "txn_ngn_001",
    "status": "SETTLED",
    "rail": "NGN_BANK",
    "currency": "NGN",
    "amount": "50000.000000",
    "debit_currency": "USD",
    "debit_scope": "MERCHANT",
    "debit_amount": "32.290323",
    "fee": "0.032258",
    "rate": {
      "side": "SELL",
      "value": "1550.00",
      "captured_at": "2026-01-05T15:04:05Z"
    },
    "on_behalf_of": null,
    "created_at": "2026-01-05T15:04:05Z",
    "settled_at": "2026-01-05T15:10:00Z"
  },
  "timestamp": "2026-01-05T15:10:00Z"
}

Customer Verification Approved

{
  "event": "customer.verification.approved",
  "id": "450e8400-e29b-41d4-a716-446655440004",
  "data": {
    "id": "650e8400-e29b-41d4-a716-446655440000",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "tier_1_kyc_complete": true,
    "tier_2_kyc_complete": true,
    "is_verified": true,
    "capabilities": [
      {
        "name": "base",
        "status": "approved"
      },
      {
        "name": "usd_banking",
        "status": "approved"
      }
    ],
    "rejection_reasons": [],
    "created_at": "2026-01-05T15:04:05Z",
    "updated_at": "2026-01-05T16:00:00Z"
  },
  "timestamp": "2026-01-05T16:00:00Z"
}

Bank Account Verification Succeeded

{
  "event": "customer.bank_account_verification.succeeded",
  "id": "3da53d16-dd57-4bf8-a8af-39944f637d81",
  "data": {
    "customer_id": "650e8400-e29b-41d4-a716-446655440000",
    "provider": "PAYSTACK",
    "status": "VERIFIED",
    "identity_version": 1
  },
  "timestamp": "2026-08-10T12:05:00Z"
}

Bank Account Verification Failed

{
  "event": "customer.bank_account_verification.failed",
  "id": "93de81e1-268f-4c79-80bd-ccaa4349b742",
  "data": {
    "customer_id": "650e8400-e29b-41d4-a716-446655440000",
    "provider": "PAYSTACK",
    "status": "FAILED",
    "identity_version": 1,
    "failure_code": "BVN_OR_ACCOUNT_NAME_MISMATCH",
    "failure_message": "Account name or BVN is incorrect"
  },
  "timestamp": "2026-08-10T12:05:00Z"
}

​Overview

​Common Payload Fields

​Data Shapes

​Deposit Events

​Funding Account Events

​Transfer Events

​Withdrawal Events

​Customer Verification Events

​Customer Bank Account Verification Events

​Bank Account Verification Events

​Lifecycle Examples

​Funding Account Deposit

​USD Virtual Account Deposit

​Internal Balance to NGN Bank Transfer

​Crypto Wallet Withdrawal

​Payload Examples

​Funding Account Active

​Deposit Completed

​Transfer Completed

​Customer Verification Approved

​Bank Account Verification Succeeded

​Bank Account Verification Failed

​Next Steps

Webhook Overview

Webhook Verification

Overview

Common Payload Fields

Data Shapes

Deposit Events

Funding Account Events

Transfer Events

Withdrawal Events

Customer Verification Events

Customer Bank Account Verification Events

Bank Account Verification Events

Lifecycle Examples

Funding Account Deposit

USD Virtual Account Deposit

Internal Balance to NGN Bank Transfer

Crypto Wallet Withdrawal

Payload Examples

Funding Account Active

Deposit Completed

Transfer Completed

Customer Verification Approved

Bank Account Verification Succeeded

Bank Account Verification Failed

Next Steps