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

Field	Type	Required	Description
`id`	string	Yes	Unique merchant identifier
`name`	string	Yes	Merchant business name
`status`	enum	Yes	Merchant status: `ACTIVE`, `INACTIVE`, `BLOCKED`
`timestamp`	number	Yes	Unix timestamp in milliseconds
`riskLevel`	string	No	Pre-assigned risk level if available
`mcc`	string	No	Merchant Category Code
`tradingName`	string	No	DBA (Doing Business As) name
`organizationId`	string	No	Parent organization identifier
`posMode`	string	No	Point of Sale mode, if applicable
`businessSegment`	string	No	Business industry segment
`averagePurchaseSize`	string	No	Average transaction size, if applicable
`monthlyVolume`	string	No	Expected monthly transaction volume, if applicable
`province`	string	No	Merchant location province/state
`country`	string	No	Merchant location country code
`paymentMethods`	array	No	Accepted payment methods, array including: `cash`, `vas`, `card`, `bank`, `crypto`, `ewa`
`registrationNumber`	string	No	Business registration/tax ID
`verificationStatus`	enum	No	Verification status: `PENDING`, `APPROVED`, `DECLINED`, `BLOCKED`
`accountNumber`	string	No	Merchant account number
`bankId`	string	No	Merchant bank identifier
`agentId`	string	No	Identifier of agent or distributor

Example Request


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

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"
    }
  ]
}

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

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for entity screened
`riskLevel`	enum	Yes	Risk level: `low`, `medium_low`, `medium`, `high`, `very_high`
`recommendedAction`	enum	Yes	Action to take: `ALLOW`, `REVIEW`, `BLOCK`, `STEP_UP_AUTH`, `FLAG_FOR_MONITORING`, `REPORT_SUSPICIOUS`
`triggered`	array	No	Array of triggered risk rules
`timestamp`	number	Yes	Unix epoch milliseconds

Triggered Rule Schema

Field	Type	Description
`id`	string	Unique identifier for the triggered rule
`name`	string	Name of the triggered rule
`level`	enum	Rule severity: `low`, `medium_low`, `medium`, `high`, `very_high`
`reason`	string	Reason for the triggered rule
`recommendedAction`	enum	Suggested action: `ALLOW`, `REVIEW`, `BLOCK`, `STEP_UP_AUTH`, `FLAG_FOR_MONITORING`, `REPORT_SUSPICIOUS`