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

When paymentMethod is set, the matching object below must be present, otherwise the request is rejected:

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:

A recipient accepts every field of the User Schema — id, firstName, lastName, dateOfBirth, address, phone, email, documents, kycDetail, amlDetail and the rest, all optional — plus the recipient-specific fields below. Recipient identity and KYC data feeds counterparty rules, so send what you have.

As with the transaction itself, when recipient.paymentMethod is set the matching object must be present, otherwise the request is rejected.

The same fields apply to each entry of the recipients array.

Example Request

{
  "id": "TXN123456",
  "userId": "USER789",
  "merchantId": "MERCH123456",
  "status": "APPROVED",
  "paymentMethod": "card",
  "card": {
    "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 the following 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
• n/a: No risk assessment was produced, typically because no rules evaluated

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
• STEP_UP_KYC: Request additional KYC information
• STEP_UP_ID: Request additional identity verification
• FLAG_FOR_MONITORING: Allow but monitor for suspicious patterns
• REPORT_SUSPICIOUS: Consider reporting to appropriate authorities
• MESSAGE_USER: Contact the user
• MESSAGE_MERCHANT: Contact the merchant

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.

Any method object you include must be non-empty — sending "bank": {} is rejected. Only accountId, paymentMethod, bank, card, vas and cash are updatable here; other transaction fields are ignored.

Deprecated feedback object

feedback predates the top-level update fields and is retained only for existing integrations. It will be removed. New integrations should send status, type, description and timestamp at the top level instead.

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

Address Schema

Used by billingAddress, the User address field, and the billingAddress inside the bank and card objects. Note that two fields are required whenever an address object is sent at all — a partial address is rejected.