Skip to content

Operate

Webhooks

Receive real-time POST notifications to your server when payment events complete. Configure your endpoint and signing secret in the partner dashboard.

Set your webhook URL in the partner dashboard under Settings. The signing secret is shown once when you create your account; you can reveal or rotate it from the same page. Every event is signed with HMAC-SHA256 over timestamp.body. Verify the signature before you act on anything.
Delivery. Each event is a POST with a JSON body { event, data, timestamp } and the headers X-Webhook-Signature and X-Webhook-Timestamp (Unix seconds). Answer any 2xx within 10 seconds. Anything else (or no answer) is retried twice, after about 30 seconds and then 2 minutes; after the third attempt the event is marked failed. Do the work after you respond, and make your handler idempotent: the same event can arrive more than once.
Read the event name from event, not type. The envelope is { "event": "deposit.completed", "data": { … } }.
webhook-handler.ts (Express)
import crypto from 'crypto'

const TOLERANCE_SECONDS = 300

app.post('/webhooks/ntzs', express.raw({ type: 'application/json' }), (req, res) => {
  // 1. Verify: HMAC-SHA256 over "<timestamp>.<raw body>", hex-encoded.
  const signature = String(req.headers['x-webhook-signature'] ?? '')
  const timestamp = String(req.headers['x-webhook-timestamp'] ?? '')
  const expected = crypto
    .createHmac('sha256', process.env.NTZS_WEBHOOK_SECRET!)
    .update(`${timestamp}.${req.body.toString()}`)
    .digest('hex')

  const valid =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < TOLERANCE_SECONDS
  if (!valid || !fresh) return res.status(400).send('Invalid signature')

  // 2. Acknowledge fast, then do the work.
  res.status(200).json({ received: true })

  // The envelope: { event, data, timestamp }
  const { event, data } = JSON.parse(req.body.toString())

  switch (event) {
    case 'deposit.completed':
      // Minted. Platform wallet: credit data.endUser.reference in your ledger.
      // De-duplicate on data.depositId.
      return creditUser(data.endUser?.reference ?? data.userId, data.amountTzs, data.depositId)
    case 'withdrawal.updated':
      // data.payoutStatus: 'completed' | 'reverted' | 'reconcile_required'
      return updatePayout(data.withdrawalId, data.payoutStatus)
    case 'spend.updated':
      // Bills can fire twice: the second carries data.utilityToken.
      return updateSpend(data.spendId, data.status, data.utilityToken)
    case 'kyc.updated':
      // On 'approved', re-call POST /api/v1/users; it now has walletAddress.
      return refreshUser(data.externalId, data.kycStatus)
    case 'merchant.sale.completed':
      // De-duplicate on data.collectionId.
      return notifyMerchant(data.merchantId, data.collectionId, data.amountTzs)
    case 'ramp.settlement.completed':
    case 'ramp.settlement.failed':
      return updateSettlement(data.settlementId, event)
  }
})

Events

Every event your endpoint can receive, and the fields in its data. Fields may be added over time, so ignore the ones you do not use rather than rejecting the event. Test-mode events carry livemode: false where the field exists.

A deposit has minted. For bank transfers that is after our statement sync matches the credit (minutes, not seconds).

depositIdstringThe deposit id returned by POST /api/v1/deposits.
userIdstringThe user credited (your platform wallet’s own record for treasury collections).
amountTzsintegerAmount minted, in whole shillings.
walletAddressstringThe wallet that received the nTZS.
txHashstringThe mint transaction on Base.
pspReferencestring | nullThe payment provider’s or our reference for the collection.
endUserobject | nullPlatform-wallet collections: the { reference, name, phone } you sent. Credit that user in your own ledger.
treasuryTopUpbooleanTrue when the deposit funded your platform wallet itself rather than a collection for a user.
collectionIdstring | nullBiashara mobile-money sales: the collection.
merchantIdstring | nullBiashara mobile-money sales: the merchant.
externalReferencestring | nullBiashara sales: whatever you sent as externalReference on the pay call, echoed verbatim.
livemodebooleanFalse for test-mode events.

A cash-out reached a terminal state: paid, failed and refunded, or held for review (it fires again once resolved).

withdrawalIdstringThe withdrawal id.
externalIdstring | nullYour user’s externalId, or your endUser.reference for platform-wallet payouts.
statusstringThe withdrawal’s internal status.
payoutStatusstring"completed", "reverted" (the burn was refunded) or "reconcile_required".
receiveAmountTzsintegerWhat the recipient receives.
burnAmountTzsintegernTZS burned, fees included.
payoutReferencestring | nullThe provider’s payout reference.
payoutProviderstring | nullThe rail that paid out.
payoutErrorstring | nullWhy a payout failed, when it did.
endUserobject | nullPlatform-wallet payouts: the endUser you sent.
livemodebooleanFalse for test-mode events.

A spend that returned payoutStatus "pending" reached its terminal state. For bills it may fire a second time carrying utilityToken.

spendIdstringThe spend id.
externalIdstring | nullYour user’s externalId, or your endUser.reference.
referencestringOur reference for the payment.
statusstring"completed", "reverted" (refunded) or "reconcile_required".
kindstring | null"lipa" (merchant till) or "bill".
recipientNamestring | nullWho was paid.
principalTzsinteger | nullThe amount paid to the recipient.
burnAmountTzsintegernTZS burned, charges included.
actualChargesTzsinteger | nullCharges actually incurred.
selcomReceiptstring | nullThe provider receipt.
utilityTokenstring | nullBills: the voucher (e.g. LUKU token). Show it the moment it arrives; it can come after completion.
utilityUnitsstring | nullBills: units purchased.
utilityReceiptstring | nullBills: the biller’s receipt.
endUserobject | nullPlatform-wallet spends: the endUser you sent.
livemodebooleanFalse for test-mode events.

An identity decision was attested. On "approved", re-call POST /api/v1/users (idempotent). It now returns the walletAddress.

externalIdstringYour user’s externalId.
kycStatusstring"approved" or "rejected".
providerstring"partner_attested".
referencestringThe case reference you attested with.

A Biashara sale settled, by either tender. Fires once per sale, so de-duplicate on collectionId.

merchantIdstringThe merchant to notify.
collectionIdstringThe sale, unique per event.
amountTzsintegerSale amount.
paymentMethodstring"mobile_money" or "ntzs_balance".
payerNamestring | nullWho paid.
payerPhonestring | nullThe payer’s number.
payerUserIdstring | nullThe payer’s nTZS user, for balance payments.
externalReferencestring | nullYour reference from the pay call, echoed verbatim.
txHashstring | nullThe settlement transaction.
createdAtstringWhen the sale was made (ISO 8601).
livemodebooleanFalse for test-mode events.

A ramp settlement finished: an off-ramp paid out, or an on-ramp delivered USDC.

settlementIdstringThe settlement id.
tzsAmountintegerOff-ramp: shillings paid out.
recipientPhonestringOff-ramp to a wallet: who was paid (when known).
destinationobjectOff-ramp to a till or bill: where it was paid.
pspReferencestringOff-ramp: the provider’s payout reference.
directionstringOn-ramp: "onramp".
usdcAmountstringOn-ramp: USDC delivered.
deliveredTostringOn-ramp: the address that received it.

A ramp settlement failed. Value from a reverted off-ramp is returned as nTZS to your settlement address and used by your next off-ramp.

settlementIdstringThe settlement id.
reasonstringWhy it failed.
returnedAsNtzsTostringWhen value was returned: your settlement address.

You pressed "Send test event" in the dashboard. Use it to check your endpoint and signature verification.

messagestringAlways "Test event from the nTZS dashboard".
sentAtstringWhen the test was sent (ISO 8601).

Enterprise disbursement batches: the batch was funded from the company’s nTZS wallet (at confirm, or once a wallet top-up arrived) and its payouts were queued. Payouts of TZS 1,000,000 or more then wait for NEDApay approval.

batchIdstringThe disbursement batch.
enterpriseIdstringThe enterprise the batch belongs to.
totalAmountTzsintegerWhat the recipients are paid, in whole shillings.
serviceFeeTzsintegerThe service fee on the batch.
totalDueTzsintegerWhat the batch drew from the wallet: totalAmountTzs + serviceFeeTzs.
contractorCountintegerRecipients in the batch.
bankReferencestring | nullThe bank reference of the wallet top-up that funded it, when the batch opened one; null when the wallet already held the funds.
receivedAtstringWhen the batch was funded and its payouts queued (ISO 8601).

Enterprise disbursement batches: every payout in the batch has settled. Sent once per batch.

batchIdstringThe disbursement batch.
enterpriseIdstringThe enterprise the batch belongs to.
statusstring"completed" when every payout was paid, "failed" when any failed.
totalAmountTzsintegerThe batch total, in whole shillings.
paidAmountTzsintegerWhat was actually paid out.
contractorCountintegerRecipients in the batch.
completedCountintegerPayouts paid.
failedCountintegerPayouts that failed.
processedAtstringWhen the batch settled (ISO 8601).