Canonical API Ingestion

How to integrate WatchTower directly when your backend can produce the native transaction contract.

Required fields and supported identifiers

POST /api/v1/transactions requires id (a UUID), amount greater than zero, channel, timestamp, sender, and receiver. Both parties require a name. Currency defaults to NGN when omitted; send it explicitly for reliable integration. Account numbers are optional for monitoring, but a filing workflow can require reportable account details.

Use paymentReference for the source transaction reference. Keep id stable across retries and send an idempotency-key header.
Use sender.providerCustomerId and receiver.providerBeneficiaryId for provider references. sender.id and root reference are not supported canonical fields.
Both parties accept identifiers with type and value. Supported types are LOCAL_ACCOUNT, IBAN, WALLET, MOBILE, MERCHANT, CARD_TOKEN, PROVIDER_ID, and OTHER.
customerType accepts INDIVIDUAL or CORPORATE. It describes the customer, not every party in the transaction.
Put transaction narration in metadata.narration. Root narration is not a canonical field.

Supplied customer and filing context

Identity enrichment is optional for monitoring. Supply supported party identifiers and contact or institution details when available. Additional filing context can be supplied in metadata and completed through the console readiness workflow. Metadata retention alone does not establish that a provider-specific field has a known regulatory meaning.

Keep customer references, identity document numbers, and bank account numbers distinct. Do not substitute an internal ledger ID for a reportable bank account number.

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.

Primary endpoint and headers

POST /api/v1/transactions

x-api-key: wt_example_organization_key

idempotency-key: 8d80a7b3-2e52-4d74-9f7f-f59f14b97f86

Canonical transaction payload example

{
  "id": "6ef1b19e-245a-42f7-bbf2-c91f0cbdde27",
  "amount": 25000,
  "currency": "NGN",
  "channel": "MOBILE",
  "transactionType": "DEBIT",
  "transactionCategory": "TRANSFER",
  "timestamp": "2026-03-24T14:43:46.020Z",
  "paymentReference": "TXN-2026-000145",
  "customerType": "INDIVIDUAL",
  "sender": {
    "name": "Ada Example",
    "providerCustomerId": "customer-001",
    "accountNumber": "0123456789",
    "bankCode": "001",
    "partyType": "BANK_ACCOUNT"
  },
  "receiver": {
    "name": "Bayo Example",
    "accountNumber": "0987654321",
    "bankCode": "214",
    "partyType": "BANK_ACCOUNT"
  },
  "metadata": {
    "narration": "Family support",
    "sourceSystem": "example-payment-platform"
  }
}

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

id as a UUID
amount and currency
timestamp
channel
transaction type and category
sender and receiver names
paymentReference and supported party identifiers when available

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.

Do not expose keys

Only call the ingestion API from trusted backend services. Never place organization API keys in browsers, mobile apps, frontend bundles, or third-party scripts.