Transaction Screening

Screen transactions for risk and retrieve transaction risk assessments.

Submit Transaction

Process a new transaction and receive an immediate risk assessment for merchant payments. This endpoint enables real-time fraud detection for payment transactions in merchant environments.

Endpoint

POST /v1/transaction

Request Schema

Additional identifiers like externalId can help link transactions across different systems

Payment Method Details

The request should include one of these payment method objects based on the paymentMethod field:

The details specific to each payment method can be found in the Payment Method Schemas section below.

Recipient Details

There is also a recipient object which is only necessary if the recipient is different from the originating user

When sending funds to another party, include recipient information:

Example Request

{
  "id": "TXN123456",
  "userId": "USER789",
  "merchantId": "MERCH123456",
  "status": "APPROVED",
  "paymentMethod": "card",
  "card": {
    "id": "CARD789",
    "last4": "4321",
    "type": "CREDIT",
    "bin": "423456"
  },
  "terminalId": "TERM123",
  "amount": 1299.99,
  "currencyCode": "ZAR",
  "timestamp": 1734100200000,
  "actionType": "PURCHASE",
  "externalId": "EXT123456"
}

Example Responses

Low Risk Response

{
  "id": "TXN123456789",
  "riskLevel": "low",
  "recommendedAction": "ALLOW",
  "triggered": [],
  "timestamp": 1734100583000
}

High Risk Response

{
  "id": "TXN123456790",
  "riskLevel": "high",
  "recommendedAction": "REVIEW",
  "timestamp": 1734100583000,
  "triggered": [
    {
      "id": "TRIG123456",
      "name": "Transaction amount above threshold",
      "level": "high",
      "reason": "Transaction amount exceeds allowed purchase size",
      "recommendedAction": "REVIEW"
    }
  ]
}

Understanding Risk Levels

The response includes a risk assessment with five levels:

• low: Minimal risk, transaction can proceed
• medium_low: Slightly elevated risk, usually safe to proceed
• medium: Moderate risk, may require additional verification
• high: Significant risk, careful review recommended
• very_high: Highest risk level, manual review strongly advised

Recommended Actions

Based on the risk assessment, you’ll receive one of these recommended actions:

• ALLOW: Process the transaction normally
• REVIEW: Flag for manual review
• BLOCK: Reject the transaction
• STEP_UP_AUTH: Request additional authentication
• FLAG_FOR_MONITORING: Allow but monitor for suspicious patterns
• REPORT_SUSPICIOUS: Consider reporting to appropriate authorities

These actions can be configured according to client requirements. Reach out to support@orca-fraud.com for customization options.

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": [
            "/amount: Expected number to be greater or equal to 0"
        ]
    },
    "timestamp": 1755602195137
}

Update Transaction Endpoint

The update endpoint allows you to update transaction statuses and provide additional context about processed transactions. This data helps improve risk assessment accuracy over time.

Endpoint

POST /v1/transaction/update

Request Schema

Transaction Update Fields

The transaction field accepts a partial transaction object containing only the fields that have been updated since the transaction was originally processed:

Note: Only include fields in the transaction object that have actually changed since the original transaction was processed.

Example Update Request

{
  "transactionId": "TXN123456",
  "status": "APPROVED",
  "description": "Transaction approved after manual review",
  "reason": "Customer verification completed",
  "type": "manual_review",
  "isFraudulent": false,
  "timestamp": 1734167723000,
  "transaction": {
    "accountId": "ACC789456"
  }
}

Response

By default, this endpoint returns a simple success response:

{
  "status": "Success"
}

A validation error in the same structure as above will be returned should the request fail validation.

Monitoring Response

If monitoring is configured for your client on this endpoint, you will receive the same response structure as the transaction screening endpoint, including risk assessment:

{
  "id": "TXN123456",
  "riskLevel": "low",
  "recommendedAction": "ALLOW",
  "triggered": [],
  "timestamp": 1734167723000
}

Note: To enable monitoring on this endpoint and receive risk assessment responses, contact support@orca-fraud.com to configure this feature for your account.

Retrieve Transaction

Get risk assessment results for a specific transaction that has already been assessed.

Endpoint

GET /v1/transaction/{id}

Parameters

Example Response

{
  "id": "TXN123456",
  "riskLevel": "medium",
  "recommendedAction": "ALLOW",
  "timestamp": 1734100583000,
  "triggered": [
    {
      "id": "TRIG123456",
      "name": "Unusual hours for merchant",
      "level": "medium",
      "reason": "Merchant operating hours outside normal range",
      "recommendedAction": "ALLOW"
    }
  ]
}

Response Schema

Note: Both the POST and GET transaction endpoints return the same response structure. This allows consistent handling of transaction risk assessments regardless of how they are retrieved.

Triggered Rule Schema

Merchant Schema

The Merchant details can either be sent via the /merchant endpoint, or in an object on the /transaction request. If the merchant object is used, please omit the root merchantId field in favour of merchant.id

Payment Method Schemas

For each of the following schemas, no fields are required however some form of identifier that can be used to identify subsequent transactions is ideal.

Bank Details Schema

Card Details Schema

Crypto Details Schema

Wallet Details Schema

Support for various wallet types, such as:

• PIX (Brazil)
• M-PESA (Kenya)

EWA (Earned Wage Access) Details Schema

VAS (Value Added Service) Details Schema

Cash Details Schema