Skip to main content

​
Overview

Daya sends merchant webhooks for deposit, withdrawal, payout, and onramp lifecycle changes. All merchant webhook payloads share the same envelope: 
{
  "event": "withdrawal.settled",
  "timestamp": "2026-03-10T09:03:00Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "SETTLED"
  }
}

​
Common Payload Fields

​
event
string
Event type for the lifecycle transition that occurred.
​
timestamp
string
RFC3339 timestamp for when the event was emitted.
​
data
object
Resource payload for the event. The shape depends on the event type.

​
Deposit Events

EventTerminal?When Sent
deposit.receivedNoDeposit received (NGN or crypto)
deposit.flaggedYesDeposit is flagged for review
deposit.pending_withdrawalNoDeposit pending on-chain withdrawal
deposit.settledYesDeposit is fully settled
deposit.failedYesDeposit permanently fails

​
Withdrawal Events

EventTerminal?When Sent
withdrawal.submittedNoWithdrawal submitted to chain
withdrawal.settledYesWithdrawal confirmed on-chain
withdrawal.failedYesWithdrawal failed

​
Payout Events

EventTerminal?When Sent
payout.createdNoA payout has been created and is being processed
payout.settledYesA payout has been successfully settled
payout.failedYesA payout has failed

​
Onramp Events

EventTerminal?When Sent
onramp.createdNoOnramp created
onramp.completedYesOnramp completed
onramp.failedYesOnramp failed

​
Withdrawal Payload Shape

Withdrawal events send the public withdrawal response shape in data.
​
data.id
string
Unique withdrawal identifier.
​
data.amount_usd
string
Withdrawal amount in USD.
​
data.chain
string
Destination chain.
​
data.token
string
Token sent on-chain.
​
data.destination_address
string
Recipient on-chain address.
​
data.status
string
Current withdrawal status.
​
data.failure_code
string
Failure code for unsuccessful withdrawals, when present.
​
data.failure_message
string
Human-readable failure detail for unsuccessful withdrawals, when present.
​
data.provider_tx_id
string
Provider-side transfer identifier, when present.
​
data.tx_hash
string
On-chain transaction hash, when present.
​
data.created_at
string
When the withdrawal record was created.
​
data.updated_at
string
Last update time for the withdrawal record.
​
data.submitted_at
string
When the withdrawal was submitted to the provider, when present.
​
data.settled_at
string
When the withdrawal was settled, when present.

​
Deposit Webhook Payload Shape

Deposit webhooks now include fields for both NGN and crypto deposits:
​
data.type
string
Deposit type: NGN_DEPOSIT or CRYPTO_DEPOSIT.
​
data.id
string
Unique deposit identifier.
​
data.onramp_id
string
Associated onramp ID (nullable, for NGN deposits).
​
data.offramp_id
string
Associated offramp ID (nullable, for crypto deposits).
​
data.customer_id
string
Associated customer ID.
​
data.amount
string
Amount received.
​
data.currency
string
Deposit currency: NGN, USDC, or USDT.
​
data.settled_amount
string
Amount after conversion.
​
data.settled_currency
string
Settlement currency.
​
data.fee_amount
string
Fee deducted.
​
data.fee_currency
string
Fee currency.
​
data.rate
string
Exchange rate applied.
​
data.rate_id
string
FX rate identifier used.
​
data.status
string
Current deposit status.
​
data.settlement_status
string
Settlement progress.
​
data.settlement_mode
string
Settlement mode: ONCHAIN, INTERNAL_BALANCE, or NGN_PAYOUT.
​
data.asset
string
Stablecoin symbol (for crypto deposits).
​
data.chain
string
Blockchain network (for crypto deposits).
​
data.tx_hash
string
On-chain transaction hash (for crypto deposits).
​
data.flag_code
string
Flag code, when present.
​
data.flag_message
string
Flag description, when present.

​
Example Deposit Event

{
  "event": "deposit.settled",
  "timestamp": "2025-01-05T15:04:05Z",
  "data": {
    "type": "CRYPTO_DEPOSIT",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "onramp_id": null,
    "offramp_id": "650e8400-e29b-41d4-a716-446655440000",
    "customer_id": "750e8400-e29b-41d4-a716-446655440000",
    "amount": "1.00",
    "currency": "USDC",
    "settled_amount": "1.00",
    "settled_currency": "USD",
    "fee_amount": "0.01",
    "fee_currency": "USD",
    "rate": "1.00",
    "rate_id": null,
    "status": "COMPLETED",
    "settlement_status": "COMPLETED",
    "settlement_mode": "INTERNAL_BALANCE",
    "asset": "USDC",
    "chain": "ETHEREUM",
    "tx_hash": "0xa1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
    "flag_code": null,
    "flag_message": null,
    "created_at": "2025-01-05T15:04:05Z",
    "updated_at": "2025-01-05T15:04:05Z"
  }
}

​
Payout Webhook Payload Shape

​
data.type
string
Payout type: NGN_PAYOUT or CRYPTO_PAYOUT.
​
data.id
string
Unique payout identifier.
​
data.reference
string
Merchant reference string.
​
data.status
string
Payout status: PROCESSING, SETTLED, or FAILED.
​
data.rail
string
Delivery rail: NGN_BANK or CRYPTO.
​
data.source_currency
string
Source currency.
​
data.destination_currency
string
Destination currency.
​
data.source_amount
string
Amount debited from source.
​
data.destination_amount
string
Amount delivered to destination.
​
data.fee
string
Fee charged.
​
data.rate
object
Exchange rate object with side, value, and captured_at.
​
data.sender
object
Sender object with type (MERCHANT or CUSTOMER) and id.
​
data.tx_hash
string
On-chain transaction hash (nullable, for crypto payouts).
​
data.created_at
string
When the payout was created.
​
data.settled_at
string
When the payout was settled, when present.

​
Example Payout Event

{
  "event": "payout.settled",
  "timestamp": "2025-01-05T15:10:00Z",
  "data": {
    "type": "NGN_PAYOUT",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "reference": "PAY-123456",
    "status": "SETTLED",
    "rail": "NGN_BANK",
    "source_currency": "USD",
    "destination_currency": "NGN",
    "source_amount": "100.00",
    "destination_amount": "155050.00",
    "fee": "1.50",
    "rate": {
      "side": "SELL",
      "value": "1550.50",
      "captured_at": "2025-01-05T15:04:05Z"
    },
    "sender": {
      "type": "MERCHANT",
      "id": "850e8400-e29b-41d4-a716-446655440000"
    },
    "tx_hash": null,
    "created_at": "2025-01-05T15:04:05Z",
    "settled_at": "2025-01-05T15:10:00Z"
  }
}

​
Example Withdrawal Events

{
  "event": "withdrawal.submitted",
  "timestamp": "2026-03-10T09:01:00Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "amount_usd": "12.3400",
    "chain": "POLYGON",
    "token": "USDT",
    "destination_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "status": "SUBMITTED",
    "failure_code": "",
    "failure_message": "",
    "provider_tx_id": "transactions/abc123",
    "tx_hash": "",
    "created_at": "2026-03-10T09:00:00Z",
    "updated_at": "2026-03-10T09:01:00Z",
    "submitted_at": "2026-03-10T09:01:00Z",
    "settled_at": ""
  }
}

​
Next Steps

Webhook Overview

Delivery guarantees, retries, and handler guidance

Webhook Verification

Verify the HMAC signature on incoming requests