Transaction Scoring API

This guide provides comprehensive information about the EagleSense transaction scoring API, including real-time evaluation and delayed attribute updates. This page describes methods for online prediction only. Uploading historical data and batch transaction scoring are covered separately and are available exclusively through S3.

Please note, in live EagleSense operation, it is crucial that we receive the status of all previous charge attempts — including CITs (even if they are not sent for scoring), MITs, Initials, and Rebills — for a given user and order before a new retry is submitted for scoring. This ensures we can recalculate aggregate features with full context prior to the next evaluation. You will use Batch Transaction Scoring method to send all processed transactions with their statuses (CITs, MITs, initials, and rebills), ensuring we receive complete transaction history and details regardless of whether a transaction requires scoring.

In addition, customer-initiated subscription transactions (CITs) may also be submitted to EagleSense for scoring directly, following this guide.

Real-Time Transaction Evaluation

Endpoint:

POST https://eaglesense.ai/data/realtime/transaction/evaluation

Authentication:

Please refer to the Authentication documentation for details on assuming the required AWS IAM role and configuring your requests with proper AWS Signature Version 4 authentication.

Request Body:

{
  "user_id": "usr_789123456",
  "card_id": "card_abc987654",
  "merchant_transaction_id": "merch_txn_2024081401234567",
  "transaction_timestamp": "2024-08-14T15:30:45Z",
  "site_name": "StreamingPlatform",
  "action_platform": "web",
  "subscription_id": "sub_premium_456789",
  "package_id": "pkg_monthly_premium",
  "ref_token": "ref_xyz789012345",
  "payment_method_type": "credit_card",
  "transaction_amount": 12.99,
  "decline_reason": null,
  "acquirer_name": "VISA_PROCESSOR",
  "order_id": "ord_20240814_987654",
  "transaction_mid": "mid_streaming_001",
  "transaction_type": "purchase",
  "order_type": "subscription",
  "transaction_descriptor": "STREAMING_MONTHLY_SUB",
  "transaction_initiation": "cit",
  "refund": false,
  "refund_reason": null,
  "transaction_status": "completed",
  "authorization_type": "3ds_authenticated",
  "authorization_settle_time": "2024-08-14T15:32:10Z",
  "merchant_category_code": "5815",
  "transaction_currency": "USD",
  "transaction_currency_displayed": "USD",
  "transaction_currency_charged": "USD",
  "exchange_rate": 1.0,
  "3ds_transaction": true,
  "hashed_ip_address_network": "sha256_net_abc123",
  "hashed_ip_address_host": "sha256_host_def456",
  "ip_address": "192.168.1.100",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "device_fingerprint": "fp_device_789abc123def",
  "device_language": "en-US",
  "product_description": "Monthly Premium Subscription",
  "card_bin": "424242",
  "bank_name": "Chase Bank",
  "card_timestamp_added": "2024-07-15T10:20:30Z",
  "bin_risk_level": "low",
  "last4": "4242",
  "card_expiration_timestamp": "2027-12-31T23:59:59Z",
  "card_brand": "visa",
  "card_level": "standard",
  "card_type": "credit",
  "cardholder_name": "John Smith",
  "card_country": "US",
  "card_billing_address": "123 Main St, New York, NY 10001",
  "multi_user_id": "multi_usr_family_001",
  "multi_user_ids": "usr_789123456,usr_789123457,usr_789123458",
  "multi_card_ids": "card_abc987654,card_abc987655",
  "related_data": "family_plan:true,primary_user:usr_789123456",
  "users_count": 3,
  "user_age": 32,
  "user_country": "US",
  "login_country": "US",
  "user_signup_timestamp": "2024-03-15T09:15:22Z",
  "traffic_source": "organic_search",
  "signup_method": "email",
  "local_timestamp": "2024-08-14T11:30:45-04:00",
  "local_timezone": "America/New_York",
  "user_status": "active",
  "user_last_log_timestamp": "2024-08-14T14:45:12Z",
  "local_language": "en-US",
  "email_domain": "gmail.com",
  "hashed_username_email": "sha256_email_user789",
  "email": "[email protected]",
  "phone_number": "[phone]",
  "address1": "123 Main Street",
  "address2": "Apartment 4B",
  "city": "New York",
  "country": "United States",
  "country_code": "US",
  "province": "New York",
  "province_code": "NY",
  "zip_code": "10001",
  "user_action_time": "2024-08-14T15:30:45Z",
  "user_engagement_time": 45.5,
  "user_other_product_usage": "streaming,music,cloud_storage",
  "user_first_session_timestamp": "2024-03-15T09:30:00Z",
  "user_last_session_timestamp": "2024-08-14T14:45:12Z",
  "user_sessions_count": 156,
  "subscription_status": "active",
  "subscription_auto_renewal": true,
  "subscription_start_timestamp": "2024-07-14T15:30:45Z",
  "subscription_end_timestamp": "2024-09-14T15:30:45Z",
  "subscription_initial_price": 9.99,
  "subscription_initial_period": "monthly",
  "subscription_recurring_price": 12.99,
  "subscription_recurring_period": "monthly",
  "premium_subscription_status": "active",
  "premium_subscription_auto_renewal": true,
  "premium_subscription_start_timestamp": "2024-07-14T15:30:45Z",
  "premium_subscription_end_timestamp": "2024-09-14T15:30:45Z",
  "payment_method_id": "pm_card_visa_4242",
  "brand_id": "brand_streaming_platform",
  "buyer_timestamp_creation": "2024-03-15T09:15:22Z"
}

Please note: the transaction_initiation field is optional. If not provided, it will automatically default to a non-CIT value. You only need to include this field when explicitly identifying customer-initiated transactions (CITs).

Response Format:

{
  "merchant_transaction_id": "your_merchant_transaction_id",
  "transaction_id": "internal_eaglesense_transaction_id",
  "error": "null/<error_message>"
}

Retrieving Evaluation Results

Endpoint:

GET https://eaglesense.ai/data/realtime/transaction/result?merchant_transaction_id=<id>

Authentication:

Please refer to the Authentication documentation for details on assuming the required AWS IAM role and configuring your requests with proper AWS Signature Version 4 authentication.

Response Format:

{
  "merchant_transaction_id": "your_merchant_transaction_id",
  "transaction_id": "internal_eaglesense_transaction_id",
  "result": {
    "risk_status": 0/1/2...
  },
  "error": "null/<error_message>"
}

Field Descriptions:

• risk_status: Integer — assigned risk category:

  • 0 – Transaction with low indication of risk

  • 1 – Transaction with high indication of risk

  • 2 - Transaction marked for skipping

Error Responses:

• 404 Not Found: Results not available yet

• 400 Bad Request: Missing client ID

• 500 Internal Server Error: Processing or storage errors

Updating Transaction Data with Delayed Attributes

This section covers updating transaction data with delayed attributes such as refunds, chargebacks, and other post-transaction events.

Endpoint:

PUT https://eaglesense.ai/data/realtime/transaction/updates

Authentication:

Please refer to the Authentication documentation for details on assuming the required AWS IAM role and configuring your requests with proper AWS Signature Version 4 authentication.

Request Body:

{
  "merchant_transaction_id": "merch_txn_2024081401234567",
  "order_id": "ord_20240814_987654",
  "decline_reason": "insufficient_funds",
  "refund": false,
  "refund_reason": null,
  "transaction_status": "declined",
  "risk_event_timestamp": "2024-08-14T15:30:45Z",
  "alert_type": "high_risk_transaction",
  "alert_reason": "multiple_failed_attempts",
  "alert_usd_cost": 25.00,
  "alert_status": "active",
  "chargeback": false,
  "chargeback_timestamp": null,
  "chargeback_reason": null,
  "fraud": false,
  "fraud_prevention": true,
  "fraud_prevention_type": "machine_learning",
  "fraud_report_source": "automated_system"
}

Response Format:

{
  "merchant_transaction_id": "your_merchant_transaction_id",
  "transaction_id": "internal_eaglesense_transaction_id",
  "error": "null/<error_message>"
}

Error Responses:

• 400 Bad Request: Invalid attribute format or values

• 404 Not Found: Transaction not found

• 409 Conflict: Conflicting attribute updates

• 500 Internal Server Error: Processing or storage errors