Using the examples

Using the examples

These pages give complete, copy-pasteable requests for the transaction ingest API, one page per account holder type and per counterparty type, followed by every response your integration can receive. Use them alongside the field reference in Submitting transactions.

Every value in these examples is synthetic. Names, account numbers, BVNs, card identifiers, IP addresses and references are invented for illustration. Never copy production customer data into test requests, tickets or logs.

The examples use NGN as the institution base currency. It is only an example base currency: use the base currency your administrator configured under Transaction Monitoring → Settings. See Transaction monitoring settings.

The account holder is not "the sender"

Every transaction is recorded against an account holder: your institution's own customer (CUSTOMER) or general ledger account (INTERNAL_GL) whose book the entry posts to. The account holder is the same party whichever way the money moves:

So on an INBOUND transaction the account holder is the recipient, and the party who sent the money is the counterparty. Use direction to tell sending from receiving; never read accountHolder as the sender.

The endpoint

POST /api/transactions

Each request submits exactly one transaction and receives OneView's decision in the same response. There is no batch endpoint. Use the exact path: a trailing slash is not accepted.

Authentication and headers

Authenticate with an API service account whose module scope is Transaction Monitoring or All licensed modules. See API Service Accounts to create one.

• The service account's credential determines which tenant the transaction belongs to. Do not send a tenant field in the body. The simplest integration omits the X-Tenant-Id header entirely.
• Call the API from your servers, not from a browser. Server-to-server requests should not send an Origin header.
• The request body can be at most 1 MB.
• There is no separate idempotency header. The transaction reference and direction make every request safely repeatable. See Replays in Decision responses.

Before the first request, an administrator must set the base currency, and the licence must include the Transaction monitoring module with its Transactions sub-module. Rules, blacklist screening, PEP and sanction screening, and geography risk are optional licensed controls. When one is not licensed or not enabled, the request still succeeds, and only the decision changes.

The minimal request

This is the smallest valid body. Every field shown is required.

POST /api/transactions
Authorization: Bearer <oneview-service-account-api-key>
Content-Type: application/json

{
  "transactionReference": "TXN-20260921-000001",
  "direction": "OUTBOUND",
  "accountHolderType": "CUSTOMER",
  "paymentMethod": "NIP",
  "channel": "MOBILE_APP",
  "status": "POSTED",
  "isCrossBorder": false,
  "amount": "25000.00",
  "currency": "NGN",
  "executedAt": "2026-09-21T09:15:00Z",
  "accountHolder": {
    "customerUniqueId": "CUS-100231"
  },
  "counterparty": {
    "counterpartyType": "EXTERNAL_BANK",
    "accountName": "Demo Recipient Limited"
  }
}

A minimal request is valid, but it gives rules very little to work with. The pages that follow add the fields rules commonly read.

Formats to get right

• Send amounts as strings, for example "25000.00". Numbers are accepted but converted to text, and 150000, "150000.0" and "150000.00" count as different values when OneView compares a retry with the original request. Amounts allow up to 14 whole digits and 4 decimal places, without leading zeros.
• Timestamps are ISO 8601 with Z or an offset, such as 2026-09-21T10:15:00+01:00. OneView stores them in UTC.
• Free text such as narration must not contain control characters, including line breaks.
• Codes such as sourceOfFunds and remittancePurposeCode use letters, digits, ., _ and -, starting with a letter or digit. sourceOfFunds can be up to 64 characters and remittancePurposeCode up to 32.
• References use the transactionReference characters. transactionReference can be up to 64 characters and externalReference up to 128.
• Required names and IDs must contain at least one non-space character. A blank customerUniqueId, accountName, merchantName or billerName is rejected as if it were missing.
• The body must be well-formed JSON. A malformed body is rejected with 400 INVALID_JSON before the API key is checked.
• Unknown top-level fields are rejected. A typo fails immediately instead of being dropped. OneView-assigned values, such as transactionId, riskScore or decision, are also rejected.
• Inside accountHolder, counterparty and telemetry, extra keys are stored as sent. Each object can hold up to 64 keys. Values can be strings of up to 512 characters, numbers, booleans, null, or one level of nested object. Arrays and the NUL character (U+0000) are not accepted. For a customer account holder, profile values have their own limits. See Customer account holder.

A rule that reads a key you did not send simply does not match. For example, card velocity rules never fire if you omit cardFingerprint. Send the keys your institution's rules use.

Choose the account holder and counterparty

Pick the account holder from whose account the entry posts to, then the counterparty from who is on the other side.

Which counterparty types fit which payment methods and channels

The API does not enforce these pairings. They are the combinations that describe real activity accurately, which is what makes rules scoped by method or channel reliable.

Add context

• Collection channels covers static account, wallet and mobile money collections. On a static account transfer a third party, the collection account, joins the account holder and the counterparty; a wallet or mobile money collection has only the two. WALLET is both a payment method and a counterparty type, and the wallet or mobile money provider is identified by counterparty.institutionCode rather than by the payment method.
• Telemetry adds device, IP address and session data to any transaction.
• Decision responses shows every outcome and what your system must do with it.
• Errors lists every error and whether to retry.