Canonical API Ingestion
How to integrate WatchTower directly when your platform can produce the native WatchTower transaction contract.
Section
When to use the canonical API
Use canonical ingestion when your institution can map its upstream transaction events directly into the WatchTower contract without needing a source-specific adapter.
- your engineering team controls the transaction event shape
- you can consistently populate sender, receiver, timestamp, amount, and category fields
- you want the thinnest possible integration layer
Section
Recommended request model
- send one transaction event per request
- use organization-scoped API keys
- always attach an idempotency key
- preserve upstream references in metadata where useful
Primary endpoint
POST /api/v1/transactions
Canonical transaction payload example
{
"id": "6145917c-2354-4805-8d9b-dc82d862fb9a",
"amount": 400,
"currency": "NGN",
"channel": "MOBILE",
"transactionType": "DEBIT",
"transactionCategory": "AIRTIME",
"timestamp": "2026-03-24T14:43:46.020Z",
"sender": {
"name": "Customer 56515218",
"accountNumber": "2212205409",
"bankCode": "UNKNOWN",
"partyType": "BANK_ACCOUNT"
},
"receiver": {
"name": "TopUp Airtime",
"accountNumber": "09113623943",
"bankCode": "BILLER",
"partyType": "MOBILE_NUMBER"
},
"sessionId": "ad6be656-69d7-53a7-9dcf-2f53a2efcafb",
"metadata": {
"flowName": "bill_payment",
"itemCategory": "Airtime",
"tenant": "sample-wallet-ng"
}
}Section
Best fit
Canonical API ingestion is best when the customer has a mature backend team and wants to integrate straight into WatchTower without an institution-specific translation layer.
Next UpAdapter API Ingestion
Continue Through The DocsWatchTower Integration Guides