Operate
Webhooks
Receive real-time POST notifications to your server when payment events complete. Configure your endpoint and signing secret in the partner dashboard.
timestamp.body. Verify the signature before you act on anything.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.event, not type. The envelope is { "event": "deposit.completed", "data": { … } }.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).
| depositId | string | The deposit id returned by POST /api/v1/deposits. |
| userId | string | The user credited (your platform wallet’s own record for treasury collections). |
| amountTzs | integer | Amount minted, in whole shillings. |
| walletAddress | string | The wallet that received the nTZS. |
| txHash | string | The mint transaction on Base. |
| pspReference | string | null | The payment provider’s or our reference for the collection. |
| endUser | object | null | Platform-wallet collections: the { reference, name, phone } you sent. Credit that user in your own ledger. |
| treasuryTopUp | boolean | True when the deposit funded your platform wallet itself rather than a collection for a user. |
| collectionId | string | null | Biashara mobile-money sales: the collection. |
| merchantId | string | null | Biashara mobile-money sales: the merchant. |
| externalReference | string | null | Biashara sales: whatever you sent as externalReference on the pay call, echoed verbatim. |
| livemode | boolean | False for test-mode events. |
A cash-out reached a terminal state: paid, failed and refunded, or held for review (it fires again once resolved).
| withdrawalId | string | The withdrawal id. |
| externalId | string | null | Your user’s externalId, or your endUser.reference for platform-wallet payouts. |
| status | string | The withdrawal’s internal status. |
| payoutStatus | string | "completed", "reverted" (the burn was refunded) or "reconcile_required". |
| receiveAmountTzs | integer | What the recipient receives. |
| burnAmountTzs | integer | nTZS burned, fees included. |
| payoutReference | string | null | The provider’s payout reference. |
| payoutProvider | string | null | The rail that paid out. |
| payoutError | string | null | Why a payout failed, when it did. |
| endUser | object | null | Platform-wallet payouts: the endUser you sent. |
| livemode | boolean | False for test-mode events. |
A spend that returned payoutStatus "pending" reached its terminal state. For bills it may fire a second time carrying utilityToken.
| spendId | string | The spend id. |
| externalId | string | null | Your user’s externalId, or your endUser.reference. |
| reference | string | Our reference for the payment. |
| status | string | "completed", "reverted" (refunded) or "reconcile_required". |
| kind | string | null | "lipa" (merchant till) or "bill". |
| recipientName | string | null | Who was paid. |
| principalTzs | integer | null | The amount paid to the recipient. |
| burnAmountTzs | integer | nTZS burned, charges included. |
| actualChargesTzs | integer | null | Charges actually incurred. |
| selcomReceipt | string | null | The provider receipt. |
| utilityToken | string | null | Bills: the voucher (e.g. LUKU token). Show it the moment it arrives; it can come after completion. |
| utilityUnits | string | null | Bills: units purchased. |
| utilityReceipt | string | null | Bills: the biller’s receipt. |
| endUser | object | null | Platform-wallet spends: the endUser you sent. |
| livemode | boolean | False for test-mode events. |
An identity decision was attested. On "approved", re-call POST /api/v1/users (idempotent). It now returns the walletAddress.
| externalId | string | Your user’s externalId. |
| kycStatus | string | "approved" or "rejected". |
| provider | string | "partner_attested". |
| reference | string | The case reference you attested with. |
A Biashara sale settled, by either tender. Fires once per sale, so de-duplicate on collectionId.
| merchantId | string | The merchant to notify. |
| collectionId | string | The sale, unique per event. |
| amountTzs | integer | Sale amount. |
| paymentMethod | string | "mobile_money" or "ntzs_balance". |
| payerName | string | null | Who paid. |
| payerPhone | string | null | The payer’s number. |
| payerUserId | string | null | The payer’s nTZS user, for balance payments. |
| externalReference | string | null | Your reference from the pay call, echoed verbatim. |
| txHash | string | null | The settlement transaction. |
| createdAt | string | When the sale was made (ISO 8601). |
| livemode | boolean | False for test-mode events. |
A ramp settlement finished: an off-ramp paid out, or an on-ramp delivered USDC.
| settlementId | string | The settlement id. |
| tzsAmount | integer | Off-ramp: shillings paid out. |
| recipientPhone | string | Off-ramp to a wallet: who was paid (when known). |
| destination | object | Off-ramp to a till or bill: where it was paid. |
| pspReference | string | Off-ramp: the provider’s payout reference. |
| direction | string | On-ramp: "onramp". |
| usdcAmount | string | On-ramp: USDC delivered. |
| deliveredTo | string | On-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.
| settlementId | string | The settlement id. |
| reason | string | Why it failed. |
| returnedAsNtzsTo | string | When value was returned: your settlement address. |
You pressed "Send test event" in the dashboard. Use it to check your endpoint and signature verification.
| message | string | Always "Test event from the nTZS dashboard". |
| sentAt | string | When 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.
| batchId | string | The disbursement batch. |
| enterpriseId | string | The enterprise the batch belongs to. |
| totalAmountTzs | integer | What the recipients are paid, in whole shillings. |
| serviceFeeTzs | integer | The service fee on the batch. |
| totalDueTzs | integer | What the batch drew from the wallet: totalAmountTzs + serviceFeeTzs. |
| contractorCount | integer | Recipients in the batch. |
| bankReference | string | null | The bank reference of the wallet top-up that funded it, when the batch opened one; null when the wallet already held the funds. |
| receivedAt | string | When the batch was funded and its payouts queued (ISO 8601). |
Enterprise disbursement batches: every payout in the batch has settled. Sent once per batch.
| batchId | string | The disbursement batch. |
| enterpriseId | string | The enterprise the batch belongs to. |
| status | string | "completed" when every payout was paid, "failed" when any failed. |
| totalAmountTzs | integer | The batch total, in whole shillings. |
| paidAmountTzs | integer | What was actually paid out. |
| contractorCount | integer | Recipients in the batch. |
| completedCount | integer | Payouts paid. |
| failedCount | integer | Payouts that failed. |
| processedAt | string | When the batch settled (ISO 8601). |