Canonical API Ingestion
How to integrate WatchTower directly when your backend can produce the native transaction contract.
When to use the canonical API
Canonical ingestion is the simplest path when your backend can map upstream transaction events directly into the WatchTower transaction contract. It keeps your integration thin because no source-specific translation layer is required.
Use this path when
- your team controls the event shape
- sender, receiver, timestamp, amount, category, and channel fields are stable
- you want one straightforward ingestion route
- your platform can safely store and use an organization API key server-side
Request model
Send one transaction event per request. Use the organization API key for authentication and an idempotency key for safe retries. Preserve upstream references in metadata so your support team can reconcile WatchTower records with your source system.
{
"reference": "TXN-2026-000145",
"amount": 25000,
"currency": "NGN",
"channel": "MOBILE",
"transactionType": "DEBIT",
"transactionCategory": "TRANSFER",
"timestamp": "2026-03-24T14:43:46.020Z",
"sender": {
"id": "cus_12345",
"name": "Ada Okafor",
"accountNumber": "0123456789",
"bankCode": "001",
"partyType": "BANK_ACCOUNT"
},
"receiver": {
"name": "Bayo Musa",
"accountNumber": "0987654321",
"bankCode": "214",
"partyType": "BANK_ACCOUNT"
},
"narration": "Family support",
"device": {
"deviceId": "device_9f24",
"ipAddress": "203.0.113.42",
"userAgent": "ExampleMobile/1.0"
},
"metadata": {
"sourceSystem": "core-banking-platform",
"branchCode": "LAG-01",
"upstreamReference": "CBS-778812"
}
}What to include first
Start with fields that are stable and available in your source system. Do not delay integration because optional context is not ready yet.
First payload version
- reference
- amount and currency
- timestamp
- channel
- transaction type and category
- sender name/account or customer ID
- receiver name/account or counterparty ID
Second payload version
- narration or payment reference
- device ID and IP address
- session or request ID
- customer risk tier
- metadata for source-system reconciliation
Response handling
Treat the decision response as the immediate result of screening. Your system should persist the transaction reference, WatchTower response, and idempotency key so both teams can reconcile behavior during support or audit reviews.
Only call the ingestion API from trusted backend services. Never place organization API keys in browsers, mobile apps, frontend bundles, or third-party scripts.