Merchant Risk Screening

Screen merchant risk levels and obtain pre-transaction risk assessments.

Endpoint

POST /v1/merchant

Request

The request must include merchant details for risk assessment. Risk assessment is configured via Client Config. Please contact support@orca-fraud.com to enable.

Request Schema

Limits

Conditional Requirements

Three pairs of fields must be sent together. Sending the second without the first is rejected with a VALIDATION_ERROR:

timestamp must also not be in the future.

Example Request

{
  "id": "MERCH123456",
  "name": "Example Retail Store",
  "status": "active",
  "mcc": "5411",
  "tradingName": "The Retail Store",
  "businessSegment": "retail",
  "businessType": "sole_proprietorship",
  "averagePurchaseSize": "120.50",
  "monthlyVolume": "250000",
  "country": "ZA",
  "province": "Western Cape",
  "registrationNumber": "2021/123456/07",
  "timestamp": 1734100200000
}

Organizations with Multiple Merchants

An organization that trades from more than one location — branch, store, outlet, franchise, depot — registers each location as its own merchant record, and sets organizationId to the same parent organization identifier on every one of them.

There is no separate object for a location and no location-specific fields. Each trading location is a merchant, described with the fields in the Request Schema above, and every value is held per merchant record. A merchant’s risk level, settlement arrangement, limits, MCC and business segment are therefore independent of the other merchants in the same organization.

{
  "id": "MERCH000042",
  "organizationId": "ORG123456",
  "name": "Example Retail Woodstock",
  "tradingName": "Woodstock Superstore",
  "status": "active",
  "riskLevel": "medium",
  "mcc": "5411",
  "businessType": "franchise",
  "businessSegment": "grocery",
  "averagePurchaseSize": "85.00",
  "monthlyVolume": "310000",
  "paymentMethods": ["card", "cash"],
  "accountNumber": "62001234567",
  "bankName": "Example Bank",
  "settlementEnabled": true,
  "settlementType": "daily_net",
  "limits": {
    "limitCurrencyCode": "ZAR",
    "transactionLimit": 5000,
    "dailyTransactionLimit": 100000,
    "monthlyTransactionLimit": 2000000
  },
  "timestamp": 1734100200000
}

A transaction sets merchantId to the id of the merchant it occurred at, so screening, aggregation and rule evaluation are scoped to that merchant rather than to the organization as a whole. Send either merchantId or a nested merchant object, never both.

organizationId is your own identifier and is stored as sent. It is not validated against your other merchant records, so a value that does not match the rest of the organization silently leaves that merchant ungrouped.

Values Held Per Merchant

Every field below is recorded against the individual merchant, and may differ from the values sent for other merchants in the same organization. Types, accepted formats and validation rules are as given in the Request Schema.

Settlement details and limits are read from the merchant record the transaction points at. A location that settles to a different bank account from the rest of its organization is represented by sending that account on its own merchant record, which is what lets beneficiary-mismatch screening evaluate the arrangement the transaction actually settles under.

Merchant Tenure

timestamp is recorded as the merchant’s creation date the first time we see a given id, and is not changed by later updates to that record. Send the true onboarding date on the first call for a new merchant. A timestamp in the future is rejected.

Every other field can be corrected by sending the same id again with the new values; previous values are retained as merchant history.

Expected Activity

averagePurchaseSize and monthlyVolume are strings, and give a baseline for a newly onboarded merchant that has no transaction history yet.

Send a plain decimal number, using . as the decimal separator, with no currency symbol, no thousands separator and no sign, e.g. "85.00", "310000". Neither field carries its own currency: send the currency in limits.limitCurrencyCode, and use one currency per merchant record.

Response

The response includes the risk assessment details and any triggered rules.

Example Response - Low Risk

{
  "id": "MERCH123456",
  "riskLevel": "low",
  "recommendedAction": "ALLOW",
  "timestamp": 1734100200000
}

Example Response - High Risk

{
  "id": "MERCH123456",
  "riskLevel": "high",
  "recommendedAction": "REVIEW",
  "timestamp": 1734100200000,
  "triggered": [
    {
      "id": "TRIG123456",
      "name": "High volume transactions",
      "level": "high",
      "reason": "Merchant exceeds monthly transaction volume",
      "recommendedAction": "REVIEW"
    }
  ]
}

Responses

Error Response Format

See the Error Reference section for a full description of API errors. All API errors follow a consistent JSON structure:

{
  "error": {
    "type": "ERROR_TYPE",
    "message": "Human-readable error description",
    "details": ["Additional error details (optional)"]
  },
  "timestamp": 1755602195137
}

In the case of a validation error, the format will be as follows:

{
    "error": {
        "type": "VALIDATION_ERROR",
        "message": "Request validation failed",
        "details": [
            "/id: Expected string"
        ]
    },
    "timestamp": 1755602195137
}

Response Schema

Triggered Rule Schema