Card counterparty

Use counterpartyType: "CARD" for card activity: a purchase at a point-of-sale terminal, an online card payment, or another transaction where a card and a merchant are the other side. merchantName is required. A request without it is rejected with counterparty.merchantName is required for a CARD counterparty.

Never send card secrets or a full card number. Do not send the full PAN, CVV, PIN, OTP, or any password. Identify the card with cardFingerprint, a stable token you generate for the card, and cardBin, the first 6 to 8 digits. Everything in the counterparty object is stored as sent and is visible to analysts.

Use these exact field names. bin, maskedPan and entryMode are not read by rules, so card rules never fire on them.

Field	What it means	Why it matters for monitoring
`merchantName`	Required. The merchant's trading name.	Shown to analysts on every card transaction.
`merchantId`	The acquirer's merchant ID.	Rules can count activity per merchant. Can match a merchant on your blacklist.
`merchantCategoryCode`	The four-digit MCC, as a string.	Rules on risky categories, such as gambling or money transfer.
`terminalId`	The POS terminal ID.	Rules can target a specific terminal, and analysts can see where the card was used.
`posEntryMode`	How the card was read. Use your own consistent values, such as `CHIP`, `CONTACTLESS`, `MAGSTRIPE` or `ECOMMERCE`.	Rules can treat fallback to magnetic stripe or card-not-present activity as higher risk.
`cardFingerprint`	Your stable token for the card. The same card must always produce the same value.	Card velocity rules count activity per card with it. Without it they never fire. Can match a card on your blacklist.
`cardBin`	The first 6 to 8 digits of the card number.	BIN rules, and can match a BIN on your blacklist.
`cardBrand`	Your label for the scheme, such as `VISA`, `MASTERCARD` or `VERVE`.	Scheme-specific rules.
`cardType`	Your label, such as `DEBIT`, `CREDIT` or `PREPAID`.	Card-type rules.
`cardIssuerCountry`	Country of the issuing bank, as a two-letter code.	Rules on foreign-issued cards.
`emailFingerprint`	SHA-256 hex digest of the buyer's email address, lowercased and trimmed first.	Links purchases by the same buyer without storing the address.
`country`	Where the merchant is, as a two-letter ISO 3166-1 code.	Country rules.

Purchase at a POS terminal

Your customer pays a supermarket with a debit card.

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

{
  "transactionReference": "POS-20260921-000714",
  "externalReference": "RRN-000000000714",
  "direction": "OUTBOUND",
  "accountHolderType": "CUSTOMER",
  "paymentMethod": "CARD",
  "channel": "POS",
  "status": "POSTED",
  "isCrossBorder": false,
  "amount": "42750.00",
  "currency": "NGN",
  "executedAt": "2026-09-21T18:22:07Z",
  "accountHolder": {
    "customerUniqueId": "CUS-100231",
    "accountNumber": "0012345678",
    "accountName": "Ada Demo Okafor"
  },
  "counterparty": {
    "counterpartyType": "CARD",
    "merchantName": "Demo Fresh Supermarket",
    "merchantId": "MID-000000000451",
    "merchantCategoryCode": "5411",
    "terminalId": "TID-00004510",
    "posEntryMode": "CONTACTLESS",
    "cardFingerprint": "cfp-0f9a4c7d21e84b36",
    "cardBin": "412345",
    "cardBrand": "VISA",
    "cardType": "DEBIT",
    "cardIssuerCountry": "NG",
    "country": "NG"
  }
}

The account holder is your customer, whose account the purchase is debited from. The counterparty describes the card that was used and the merchant that was paid.

Online card payment

The same customer's card is used on a merchant website. There is no terminal, the entry mode is card-not-present, and the buyer's email is sent only as a fingerprint.

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

{
  "transactionReference": "ECM-20260921-000093",
  "externalReference": "RRN-000000000093",
  "direction": "OUTBOUND",
  "accountHolderType": "CUSTOMER",
  "paymentMethod": "CARD",
  "channel": "INTERNET_BANKING",
  "status": "POSTED",
  "isCrossBorder": true,
  "amount": "89.99",
  "currency": "USD",
  "executedAt": "2026-09-21T21:03:55Z",
  "accountHolder": {
    "customerUniqueId": "CUS-100231",
    "accountNumber": "0012345678",
    "accountName": "Ada Demo Okafor"
  },
  "counterparty": {
    "counterpartyType": "CARD",
    "merchantName": "Demo Online Electronics",
    "merchantId": "MID-000000009921",
    "merchantCategoryCode": "5732",
    "posEntryMode": "ECOMMERCE",
    "cardFingerprint": "cfp-0f9a4c7d21e84b36",
    "cardBin": "412345",
    "cardBrand": "VISA",
    "cardType": "DEBIT",
    "cardIssuerCountry": "NG",
    "emailFingerprint": "70eacade7142e15d64a36ac9fe80e227ee5c26860dfad4baa70664d5f7a6c1e8",
    "country": "US"
  },
  "telemetry": {
    "ipAddress": "198.51.100.37",
    "deviceFingerprintHash": "dfp-3c1e9b7a0d5f4e22",
    "isVpnOrProxy": false,
    "country": "NG"
  }
}

The currency is USD, so usdExchangeRate is not needed even though isCrossBorder is true. OneView uses a rate of 1.
The same cardFingerprint as the POS example means card velocity rules see both purchases as the same card.
emailFingerprint here is the SHA-256 of ada.okafor@example.com. Lowercase and trim the address before hashing, or the same buyer produces different fingerprints.
Prefer emailFingerprint to email. Like any extra key inside counterparty (not a card-specific allowance — see Formats to get right in Using the examples), a raw email field is accepted and stored exactly as sent and shown to analysts.
Telemetry describes the device that placed the order. See Telemetry.

cardBrand, cardType and posEntryMode are not OneView-defined enums either. VISA/MASTERCARD/VERVE, DEBIT/CREDIT/PREPAID, and CHIP/CONTACTLESS/MAGSTRIPE/ECOMMERCE above are this example's own values — OneView accepts and stores whatever text you send in each field.

Response

This is the response to the POS purchase above:

{
  "status": true,
  "message": "Transaction evaluated",
  "data": {
    "transaction": {
      "id": "d3a3b00d-a659-484d-a756-6a2cbe42c638",
      "transactionReference": "POS-20260921-000714",
      "direction": "OUTBOUND",
      "receivedAt": "2026-09-21T18:22:07.264Z",
      "replayed": false
    },
    "decision": {
      "outcome": "PASS",
      "riskScore": 0,
      "evaluatedAt": "2026-09-21T18:22:07.281Z",
      "evaluationMs": 6.339,
      "complete": true,
      "rulesEvaluated": 12,
      "rulesetSnapshot": "5c0e8a1f93d24b6e8f7a2c1d0b9e8f7a6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f",
      "gradingVersion": 3,
      "triggeredRules": []
    }
  }
}

See BLOCK from rules for what this same transaction returns when a card velocity rule fires — that example uses this exact transactionReference.

Errors specific to a card counterparty

Cause	`field`	`code`	`message`
No `merchantName`	`counterparty`	`required`	`counterparty.merchantName is required for a CARD counterparty`
`counterparty.country` is a three-letter or unassigned code	`counterparty.country`	`invalid`	`counterparty.country must be an ISO 3166-1 alpha-2 country code`
A non-USD, cross-border transaction has no `usdExchangeRate`	`usdExchangeRate`	`required`	`usdExchangeRate is required for cross-border or foreign-currency transactions`

See Errors for the complete catalogue.

Idempotency

Deduplication is by transactionReference and direction. Card authorisation and settlement messages are frequently retried by switches and processors, so this matters here more than most: resending the identical body for the same reference and direction returns 200 with replayed: true and does not re-decision the purchase. A retried authorisation with a changed field, such as a corrected amount, is rejected with 409 IDEMPOTENCY_CONFLICT rather than silently creating a second decision for the same purchase. See Idempotency in Submitting transactions.

Merchants are not screened by name

PEP and sanction screening resolves a counterparty's name from firstName/lastName, companyName, then accountName (see Customer account holder). merchantName is not in that list, so a CARD counterparty is never screened by name — only the account holder (your customer) is. Rules and blacklist matching on merchantId, cardFingerprint, cardBin and the other card fields are unaffected.