Alogram PayRisk Logo
API docs by Redocly

Alogram PayRisk Engine (0.2.10)

Download OpenAPI specification:

Alogram Engineering: packages@alogram.ai URL: https://developers.alogram.ai License: Apache-2.0 Terms of Service

Alogram PayRisk is an AI-native decision engine built for the speed and complexity of the modern commerce era. In a high-velocity world where AI-driven threats evolve in milliseconds, Alogram provides the real-time adaptability and forensic transparency needed to protect your ecosystem with total confidence. We solve the challenge of balancing frictionless growth with regulatory explainability, delivering instant, intelligent risk orchestration at enterprise scale.

Licensing & Terms

Our client libraries and API specifications are open-source under the Apache License 2.0 to ensure seamless integration into your tech stack.

Use of the Alogram PayRisk API service is proprietary and governed by our Terms of Service and your specific Enterprise Agreement, if applicable.

To access the service, you must have:

  • A valid Alogram API Key.
  • An active subscription or signed Master Service Agreement.

Unauthorized use, including automated scraping or reverse engineering of the scoring engine, is strictly prohibited.

Support & Traceability

Every Alogram API response includes a unique x-trace-id header. Please include this ID when contacting packages@alogram.ai regarding specific transactions or errors.

Specification

The authoritative OpenAPI specification for this version is available for download: Download openapi.yaml | Download openapi.json

Risk Scoring

Real-time risk assessment and automated decision orchestration.

Assess Transaction Risk

Authorizations:
ApiKeyoAuth2
header Parameters
x-idempotency-key
required
string (IdempotencyKey) = 36 characters ^idk_[a-f0-9]{32}$
Example: idk_4f9d27e2b8f64b9e9a9cf5e9e4727d0c

Unique Idempotency-Key sent in the POST request etc.

x-trace-id
string (TraceId) = 36 characters ^trc_[a-f0-9]{32}$
Example: trc_123e4567e89b12d3a456426614174000

Echoed or generated trace ID for tracking requests.

Request Body schema: application/json
required
required
object (EntityIds)

Canonical entity identifiers (tenant/client/user/device/session). Do not send raw PII. Hash emails/phones/addresses as sha256 and prefix with 'sha256_'. Tiered support:

  • tenantId is the top-level SaaS customer (required for all flows).
  • clientId is the tenant's downstream business customer (e.g. merchant/partner) and MAY be omitted for processor / bank / PSP-style integrations.
  • endCustomerId is the tenant/client's consumer or business account (cardholder, shopper, etc.) and MAY be omitted for purely device- or instrument-level checks.
required
object (Purchase)

Purchase details for fraud checks; core fields are common, instrument specifics live in paymentMethod.

eventType
string
Default: "purchase"
Value: "purchase"

(optional) event being checked, this may expand later beyond 'purchase'.

paymentIntentId
string (PaymentIntentId) = 35 characters ^pi_[a-f0-9]{32}$

Server-minted unique payment identifier.

object (Identity)

Optional raw identity details for the account associated with the purchase. These fields (email, phone, addresses) are used for normalization, hashing, and risk feature extraction (e.g., email/phone/domain scoring, address risk), and are not stored in raw form by Alogram.

When provided, Alogram will derive and/or cross-check:

  • emailHash / phoneHash / shippingAddressHash / billingAddressHash in the internal entity model
  • email/phone/domain risk signals
  • address consistency and geo-distance checks
Array of objects (ExternalAssessment)

Optional 3rd party risk assessments (e.g. Shopify, Stripe, Signifyd).

Responses

Response Headers
x-trace-id
string (TraceId) = 36 characters ^trc_[a-f0-9]{32}$
Example: "trc_123e4567e89b12d3a456426614174000"

Echoed or generated trace ID for tracking requests, returned in the response headers.

x-idempotency-key
string (IdempotencyKey) = 36 characters ^idk_[a-f0-9]{32}$
Example: "idk_4f9d27e2b8f64b9e9a9cf5e9e4727d0c"

Echo of the request's x-idempotency-key header.

Response Schema: application/json
assessmentId
required
string [ 8 .. 64 ] characters ^[a-zA-Z0-9\-_]+$

Universal decision identifier. For purchases, equals paymentIntentId.

decision
required
string
Enum: "approve" "review" "decline" "step_up"
riskScore
required
number <float> [ 0 .. 1 ]

DEPRECATED: Use decisionScore instead. Current blended risk score.

decisionAt
required
string <timestamp with timezone> (Timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9...

RFC 3339 timestamp with timezone.

decisionScore
required
number <float> [ 0 .. 1 ]

The authoritative blended risk score (0.0 - 1.0) derived from expert fusion.

object (FraudScore)

Fraud score for a specific transaction or entity.

object (RiskBreakdown)

Breakdown of risk signals by business category.

reasonCodes
Array of strings

Technical reason codes for the decision.

Array of objects (ReasonDetail)

Structured reason details for the decision.

actions
Array of strings
Items Enum: "step_up" "throttle" "lock_account" "decline" "queue_review"
paymentIntentId
string (PaymentIntentId) = 35 characters ^pi_[a-f0-9]{32}$

Server-minted unique payment identifier.

policyVersion
string

The version of the policy that generated the decision.

modelVersion
string

The version of the model that generated the decision.

ttlSeconds
integer >= 0

Time to live for the decision in seconds.

Request samples

Content type
application/json
{
  • "paymentIntentId": "pi_0123456789abcdef0123456789abcdef",
  • "entities": {
    },
  • "identity": {
    },
  • "purchase": {
    }
}

Response samples

Content type
application/json
{
  • "assessmentId": "pi_0123456789abcdef0123456789abcdef",
  • "decision": "approve",
  • "decisionAt": "2023-12-14T15:45:30.123Z",
  • "riskScore": 0.12,
  • "fraudScore": {
    }
}

Signal Intelligence

Ingestion of payment lifecycle events and behavioral telemetry.

Ingest Lifecycle Signals

Authorizations:
ApiKeyoAuth2
header Parameters
x-idempotency-key
required
string (IdempotencyKey) = 36 characters ^idk_[a-f0-9]{32}$
Example: idk_4f9d27e2b8f64b9e9a9cf5e9e4727d0c

Unique Idempotency-Key sent in the POST request etc.

x-trace-id
string (TraceId) = 36 characters ^trc_[a-f0-9]{32}$
Example: trc_123e4567e89b12d3a456426614174000

Echoed or generated trace ID for tracking requests.

Request Body schema: application/json
required
paymentIntentId
required
string (PaymentIntentId) = 35 characters ^pi_[a-f0-9]{32}$

Server-minted unique payment identifier.

eventType
required
string (PaymentEventType)
Enum: "authorization" "capture" "settlement" "refund" "dispute" "chargeback" "chargeback_outcome"

The type of payment lifecycle event.

timestamp
required
string <timestamp with timezone> (Timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9...

RFC 3339 timestamp with timezone.

amount
number <float> (PurchaseAmount) [ 0.01 .. 10000000 ]

Value of the purchase in the specified currency. Must be a positive number with up to two decimal places.

currency
string (CurrencyCode) = 3 characters ^[A-Z]{3}$

ISO 4217 currency code (e.g., 'USD').

object (PaymentOutcome)

Payment outcome details. Structured by lifecycle stage for clarity and validation. Stages include authorization, capture, refund, dispute, chargeback, and chargebackOutcome.

metadata
string (MetaData) [ 1 .. 2048 ] characters

Optional key-value pairs providing additional context for the request. Each key should be descriptive, and values should not exceed 2048 characters. Each key should be descriptive.

Responses

Response Headers
x-trace-id
string (TraceId) = 36 characters ^trc_[a-f0-9]{32}$
Example: "trc_123e4567e89b12d3a456426614174000"

Echoed or generated trace ID for tracking requests, returned in the response headers.

x-idempotency-key
string (IdempotencyKey) = 36 characters ^idk_[a-f0-9]{32}$
Example: "idk_4f9d27e2b8f64b9e9a9cf5e9e4727d0c"

Echo of the request's x-idempotency-key header.

Request samples

Content type
application/json
{
  • "paymentIntentId": "pi_0123456789abcdef0123456789abcdef",
  • "eventType": "authorization",
  • "timestamp": "2023-12-14T15:45:30.123Z",
  • "amount": 123.45,
  • "currency": "USD",
  • "outcome": {
    }
}

Response samples

Content type
application/problem+json
{}

Submit Behavioral Intelligence

Authorizations:
ApiKeyoAuth2
header Parameters
x-idempotency-key
required
string (IdempotencyKey) = 36 characters ^idk_[a-f0-9]{32}$
Example: idk_4f9d27e2b8f64b9e9a9cf5e9e4727d0c

Unique Idempotency-Key sent in the POST request etc.

x-trace-id
string (TraceId) = 36 characters ^trc_[a-f0-9]{32}$
Example: trc_123e4567e89b12d3a456426614174000

Echoed or generated trace ID for tracking requests.

Request Body schema: application/json
required
signalType
required
string

Value for account signals.

required
object (EntityIds)

Canonical entity identifiers (tenant/client/user/device/session). Do not send raw PII. Hash emails/phones/addresses as sha256 and prefix with 'sha256_'. Tiered support:

  • tenantId is the top-level SaaS customer (required for all flows).
  • clientId is the tenant's downstream business customer (e.g. merchant/partner) and MAY be omitted for processor / bank / PSP-style integrations.
  • endCustomerId is the tenant/client's consumer or business account (cardholder, shopper, etc.) and MAY be omitted for purely device- or instrument-level checks.
required
object (Account)

The application-layer Account object.

Responses

Response Headers
x-trace-id
string (TraceId) = 36 characters ^trc_[a-f0-9]{32}$
Example: "trc_123e4567e89b12d3a456426614174000"

Echoed or generated trace ID for tracking requests, returned in the response headers.

x-idempotency-key
string (IdempotencyKey) = 36 characters ^idk_[a-f0-9]{32}$
Example: "idk_4f9d27e2b8f64b9e9a9cf5e9e4727d0c"

Echo of the request's x-idempotency-key header.

Request samples

Content type
application/json
{
  • "signalType": "interaction",
  • "entities": {
    },
  • "interactions": [
    ]
}

Response samples

Content type
application/problem+json
{}

Forensic Data

Retrieval of historical assessments and deep forensic insights.

Query Historical Assessments

Authorizations:
ApiKeyoAuth2
path Parameters
tenantId
required
string (TenantId) [ 5 .. 64 ] characters ^tid_[a-z0-9\-_]{2,60}$
Example: tid_acme_01

Canonical ID for the paying organization (Tenant). Opaque, immutable, lowercase. Must start with "tid_". Do not use domains or emails here. For a tenant's domain, use a separate field (e.g., tenantDomain).

query Parameters
startTime
string <timestamp with timezone> (Timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9...
Example: startTime=2023-12-14T15:45:30.123456Z

RFC 3339 timestamp with timezone.

endTime
string <timestamp with timezone> (Timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9...
Example: endTime=2023-12-14T15:45:30.123456Z

RFC 3339 timestamp with timezone.

pageSize
integer [ 1 .. 500 ]
Default: 50
pageToken
string
header Parameters
x-trace-id
string (TraceId) = 36 characters ^trc_[a-f0-9]{32}$
Example: trc_123e4567e89b12d3a456426614174000

Echoed or generated trace ID for tracking requests.

x-idempotency-key
string (IdempotencyKey) = 36 characters ^idk_[a-f0-9]{32}$
Example: idk_4f9d27e2b8f64b9e9a9cf5e9e4727d0c

Unique Idempotency-Key sent in the GET request etc.

Responses

Response Headers
x-trace-id
string (TraceId) = 36 characters ^trc_[a-f0-9]{32}$
Example: "trc_123e4567e89b12d3a456426614174000"

Echoed or generated trace ID for tracking requests, returned in the response headers.

x-idempotency-key
string (IdempotencyKey) = 36 characters ^idk_[a-f0-9]{32}$
Example: "idk_4f9d27e2b8f64b9e9a9cf5e9e4727d0c"

Echo of the request's x-idempotency-key header.

Response Schema: application/json
required
Array of objects (ScoreRecord)

Score records within the requested window.

nextPageToken
string <= 4096 characters

A token for retrieving the next page of results.

Response samples

Content type
application/json
{
  • "scores": [
    ],
  • "nextPageToken": "eyJhbGciOi..."
}

System

Service health and connectivity diagnostics.

Health check for the service

Responses

Roadmap & Preview

Future capabilities currently in active development or private beta.

Synchronous fraud decision for account/session events Coming Soon

Coming Soon: This endpoint is currently in active development. Assess risk for account-level events such as signup, login, and profile changes.

Authorizations:
ApiKeyoAuth2
header Parameters
x-idempotency-key
required
string (IdempotencyKey) = 36 characters ^idk_[a-f0-9]{32}$
Example: idk_4f9d27e2b8f64b9e9a9cf5e9e4727d0c

Unique Idempotency-Key sent in the POST request etc.

x-trace-id
string (TraceId) = 36 characters ^trc_[a-f0-9]{32}$
Example: trc_123e4567e89b12d3a456426614174000

Echoed or generated trace ID for tracking requests.

Request Body schema: application/json
required
eventSubtype
required
string
Enum: "signup" "login" "password_reset" "mfa_reset" "setting_change"

The specific subtype of the account event (e.g., 'signup', 'login').

object (EntityIds)

Canonical entity identifiers (tenant/client/user/device/session). Do not send raw PII. Hash emails/phones/addresses as sha256 and prefix with 'sha256_'. Tiered support:

  • tenantId is the top-level SaaS customer (required for all flows).
  • clientId is the tenant's downstream business customer (e.g. merchant/partner) and MAY be omitted for processor / bank / PSP-style integrations.
  • endCustomerId is the tenant/client's consumer or business account (cardholder, shopper, etc.) and MAY be omitted for purely device- or instrument-level checks.
object (Account)

The application-layer Account object.

object (Interaction)

The application-layer Interaction object.

Responses

Response Headers
x-trace-id
string (TraceId) = 36 characters ^trc_[a-f0-9]{32}$
Example: "trc_123e4567e89b12d3a456426614174000"

Echoed or generated trace ID for tracking requests, returned in the response headers.

x-idempotency-key
string (IdempotencyKey) = 36 characters ^idk_[a-f0-9]{32}$
Example: "idk_4f9d27e2b8f64b9e9a9cf5e9e4727d0c"

Echo of the request's x-idempotency-key header.

Response Schema: application/json
assessmentId
required
string [ 8 .. 64 ] characters ^[a-zA-Z0-9\-_]+$

Universal decision identifier. For purchases, equals paymentIntentId.

decision
required
string
Enum: "approve" "review" "decline" "step_up"
riskScore
required
number <float> [ 0 .. 1 ]

DEPRECATED: Use decisionScore instead. Current blended risk score.

decisionAt
required
string <timestamp with timezone> (Timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9...

RFC 3339 timestamp with timezone.

decisionScore
required
number <float> [ 0 .. 1 ]

The authoritative blended risk score (0.0 - 1.0) derived from expert fusion.

object (FraudScore)

Fraud score for a specific transaction or entity.

object (RiskBreakdown)

Breakdown of risk signals by business category.

reasonCodes
Array of strings

Technical reason codes for the decision.

Array of objects (ReasonDetail)

Structured reason details for the decision.

actions
Array of strings
Items Enum: "step_up" "throttle" "lock_account" "decline" "queue_review"
paymentIntentId
string (PaymentIntentId) = 35 characters ^pi_[a-f0-9]{32}$

Server-minted unique payment identifier.

policyVersion
string

The version of the policy that generated the decision.

modelVersion
string

The version of the model that generated the decision.

ttlSeconds
integer >= 0

Time to live for the decision in seconds.

Request samples

Content type
application/json
{
  • "eventSubtype": "signup",
  • "entities": {
    },
  • "account": {
    },
  • "interaction": {
    }
}

Response samples

Content type
application/json
{
  • "assessmentId": "pi_0123456789abcdef0123456789abcdef",
  • "decision": "approve",
  • "decisionAt": "2023-12-14T15:45:30.123Z",
  • "riskScore": 0.98
}

Synchronous decision for KYC/identity verification Coming Soon

Coming Soon: This endpoint is currently in active development. Assess risk for identity verification and KYC workflows.

Authorizations:
ApiKeyoAuth2
header Parameters
x-idempotency-key
required
string (IdempotencyKey) = 36 characters ^idk_[a-f0-9]{32}$
Example: idk_4f9d27e2b8f64b9e9a9cf5e9e4727d0c

Unique Idempotency-Key sent in the POST request etc.

x-trace-id
string (TraceId) = 36 characters ^trc_[a-f0-9]{32}$
Example: trc_123e4567e89b12d3a456426614174000

Echoed or generated trace ID for tracking requests.

Request Body schema: application/json
required
eventSubtype
required
string
Enum: "pre_kyc_check" "doc_scan" "liveness" "address_check" "sanctions_pep"

The specific subtype of the KYC event.

required
object (Account)

The application-layer Account object.

object (EntityIds)

Canonical entity identifiers (tenant/client/user/device/session). Do not send raw PII. Hash emails/phones/addresses as sha256 and prefix with 'sha256_'. Tiered support:

  • tenantId is the top-level SaaS customer (required for all flows).
  • clientId is the tenant's downstream business customer (e.g. merchant/partner) and MAY be omitted for processor / bank / PSP-style integrations.
  • endCustomerId is the tenant/client's consumer or business account (cardholder, shopper, etc.) and MAY be omitted for purely device- or instrument-level checks.
object (KycPayload)

KYC provider result payload.

Responses

Response Headers
x-trace-id
string (TraceId) = 36 characters ^trc_[a-f0-9]{32}$
Example: "trc_123e4567e89b12d3a456426614174000"

Echoed or generated trace ID for tracking requests, returned in the response headers.

x-idempotency-key
string (IdempotencyKey) = 36 characters ^idk_[a-f0-9]{32}$
Example: "idk_4f9d27e2b8f64b9e9a9cf5e9e4727d0c"

Echo of the request's x-idempotency-key header.

Response Schema: application/json
assessmentId
required
string [ 8 .. 64 ] characters ^[a-zA-Z0-9\-_]+$

Universal decision identifier. For purchases, equals paymentIntentId.

decision
required
string
Enum: "approve" "review" "decline" "step_up"
riskScore
required
number <float> [ 0 .. 1 ]

DEPRECATED: Use decisionScore instead. Current blended risk score.

decisionAt
required
string <timestamp with timezone> (Timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9...

RFC 3339 timestamp with timezone.

decisionScore
required
number <float> [ 0 .. 1 ]

The authoritative blended risk score (0.0 - 1.0) derived from expert fusion.

object (FraudScore)

Fraud score for a specific transaction or entity.

object (RiskBreakdown)

Breakdown of risk signals by business category.

reasonCodes
Array of strings

Technical reason codes for the decision.

Array of objects (ReasonDetail)

Structured reason details for the decision.

actions
Array of strings
Items Enum: "step_up" "throttle" "lock_account" "decline" "queue_review"
paymentIntentId
string (PaymentIntentId) = 35 characters ^pi_[a-f0-9]{32}$

Server-minted unique payment identifier.

policyVersion
string

The version of the policy that generated the decision.

modelVersion
string

The version of the model that generated the decision.

ttlSeconds
integer >= 0

Time to live for the decision in seconds.

Request samples

Content type
application/json
{
  • "eventSubtype": "pre_kyc_check",
  • "entities": {
    },
  • "account": {
    },
  • "kyc": {
    }
}

Response samples

Content type
application/json
{
  • "assessmentId": "pi_0123456789abcdef0123456789abcdef",
  • "decision": "approve",
  • "decisionAt": "2023-12-14T15:45:30.123Z",
  • "riskScore": 0.98
}