Transaction Screening

Screen transaction risk levels and process payments.

Submit Transaction

Process a new transaction and receive an immediate risk assessment. This endpoint handles various payment methods including bank transfers, card payments, and cryptocurrency transactions.

Endpoint

POST /v1/transaction

Request Schema

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": "TXN123",
  "userId": "USER123",
  "accountId": "ACCT123",
  "status": "PENDING",
  "currencyCode": "ZAR",
  "amount": 1000.00,
  "direction": "payout",
  "actionType": "withdrawal",
  "source": "savings",
  "provider": "dlocal",
  "paymentMethod": "bank",
  "bank": {
    "accountNumber": "1234567890",
    "bankCode": "051001",
    "branchCode": "123456",
    "accountType": "checking",
    "accountHolderName": "John Doe"
  },
  "billingAddress": {
    "street": "123 Main St",
    "city": "Cape Town",
    "country": "ZA",
    "postalCode": "8001"
  },
  "timestamp": 1734167723000,
  "externalId": "EXT789",
  "userDeviceId": "DEVICE123"
}

Response Schema

Example Responses

Low Risk Response

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

High Risk Response

{
  "id": "TXN123",
  "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 four recommended actions:

• ALLOW: Process the transaction normally
• REVIEW: Flag for manual review
• BLOCK: Reject the transaction
• STEP_UP_AUTH: Request additional authentication

These actions can be configured according through client config. Reach out to support@orca-fraud.com if you’d like a list of all possible actions.

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 volume",
      "level": "medium",
      "reason": "User is exhibiting unusual transactional behaviour relative to normal behaviour.",
      "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

User Schema

The User details can either be sent via the /user endpoint, or in an object on the /transaction request. If the user object is used, please omit the root userId field in favour of user.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