> ## Documentation Index > Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt > Use this file to discover all available pages before exploring further. # Evaluate transaction > Send a decision for evaluation and receive an `ALLOW`, `REVIEW`, or `BLOCK` response on synchronous rules. If an asynchronous rule (e.g. based on a backend) is involved, a `PROVISIONAL` response with later update is possible. ## OpenAPI ````yaml /products/specter/openapi.yaml post /api/decisions openapi: 3.1.0 info: contact: email: hello@starfish.team name: Starfish GmbH & Co. KG url: https://hellgate.io/cpa/specter description: Composable decision engine and fraud prevention service. license: name: Hellgate API Terms url: https://hellgate.io/terms-and-conditions title: Specter API version: '1.0' servers: - description: Managed instance of Specter url: https://{instance}.{env}.on-hellgate.cloud variables: instance: default: my-instance description: Your unique instance slug, provided during onboarding. env: default: eu1 description: Deployment environment (currently eu1). security: [] tags: - description: Evaluate transactions and retrieve decision results. name: Decisions - description: Close decisions that were flagged for manual review. name: Resolutions - description: Report payment lifecycle events for a prior decision. name: Lifecycle Events - description: Manage rulesets and their activation lifecycle. name: Rulesets - description: Configure interceptors and intercept live payment requests. name: Interceptors - description: Subscribe to decision and event notifications. name: Webhooks - description: Manage blocked field values. name: Blacklist paths: /api/decisions: post: tags: - Decisions summary: Evaluate transaction description: > Send a decision for evaluation and receive an `ALLOW`, `REVIEW`, or `BLOCK` response on synchronous rules. If an asynchronous rule (e.g. based on a backend) is involved, a `PROVISIONAL` response with later update is possible. operationId: decisions_create parameters: [] requestBody: content: application/json: examples: full: summary: Full payload value: billing: address1: 96 Powers Street city: Milford country: US first_name: James last_name: Smith postal_code: '03055' state: NH context: checkout credential: pan: cardholder_name: Sherlock Holmes expiry_month: 12 expiry_year: 2031 scheme: visa value: '4111111111111111' type: pan customer: id: cust_001 email: sherlock@example.com first_name: Sherlock last_name: Holmes device: fingerprint: fp_vdm_test ip: 1.2.3.4 language: en-GB items: - categories: - Accessories - Smoking name: Calabash Pipe price: 4900 product_type: physical quantity: 1 sku: PIPE-001 metadata: campaign: spring_2026 channel: web shipping: carrier: DHL method: STANDARD transaction: amount: 4900 currency: USD reference: ord_001 masked_pan: summary: Masked PAN value: context: checkout credential: masked_pan: expiry_month: 12 expiry_year: 2026 first_six: '411111' last_four: '1111' scheme: visa type: masked_pan customer: id: cust_123 device: fingerprint: fp_abc123 ip: 1.2.3.4 transaction: amount: 5000 currency: EUR reference: txn_abc pan: summary: Full PAN value: context: checkout credential: pan: expiry_month: 7 expiry_year: 2029 scheme: visa value: '4111111111111111' type: pan customer: id: cust_001 device: fingerprint: fp_abc123 ip: 1.2.3.4 transaction: amount: 4900 currency: EUR reference: ord_001 sepa: summary: SEPA direct debit value: context: checkout credential: sepa: iban: DE89370400440532013000 owner_name: John Doe type: sepa customer: id: cust_001 transaction: amount: 1800 currency: EUR reference: txn_001 schema: $ref: '#/components/schemas/DecisionRequest' description: Decision request required: true responses: '201': content: application/json: examples: allow: summary: ALLOW — no rules matched value: id: 9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b backend_results: [] context: checkout credential_fingerprint: crd_4ba2188f9c1e credential_type: pan decision: ALLOW evaluated_at: '2026-06-02T12:00:00Z' events: [] has_backend_error: false latency_us: 4250 masked_credential: 411111 ****** 1111 resolution: null ruleset_id: 1f2e3d4c-5b6a-4978-8c0d-1e2f3a4b5c6d ruleset_version: 3 source: RULE_ENGINE triggered_rules: [] block: summary: BLOCK — terminating rule matched value: id: a3f9c7d1-2e4b-4a6c-8f0d-9b1a3c5e7d2f backend_results: [] context: checkout credential_fingerprint: crd_4ba2188f9c1e credential_type: pan decision: BLOCK evaluated_at: '2026-06-02T12:00:00Z' events: [] has_backend_error: false latency_us: 3800 masked_credential: 411111 ****** 1111 resolution: null ruleset_id: 1f2e3d4c-5b6a-4978-8c0d-1e2f3a4b5c6d ruleset_version: 3 source: RULE_ENGINE triggered_rules: - action: BLOCK name: Block USD rule_id: r1 review: summary: REVIEW — flagged for manual review value: id: 7c2b1a90-8d7e-4f6c-9b5a-3e2d1c0b9a8f backend_results: [] context: checkout credential_fingerprint: crd_4ba2188f9c1e credential_type: pan decision: REVIEW evaluated_at: '2026-06-02T12:00:00Z' events: [] has_backend_error: false latency_us: 5100 masked_credential: 411111 ****** 1111 resolution: null ruleset_id: 1f2e3d4c-5b6a-4978-8c0d-1e2f3a4b5c6d ruleset_version: 3 source: RULE_ENGINE triggered_rules: - action: REVIEW name: Review high EUR amount rule_id: r3 schema: $ref: '#/components/schemas/DecisionResponse' description: Decision result '401': content: application/json: schema: $ref: '#/components/schemas/Unauthorized' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/Forbidden' description: Forbidden '422': content: application/json: schema: $ref: '#/components/schemas/ValidationErrors' description: Validation errors callbacks: {} security: - bearerAuth: [] components: schemas: DecisionRequest: example: billing: address1: 96 Powers Street city: Milford country: US first_name: James last_name: Smith postal_code: '03055' state: NH context: checkout credential: pan: expiry_month: 7 expiry_year: 2029 scheme: visa value: '4111111111111111' type: pan customer: id: cust_001 first_name: Sherlock last_name: Holmes device: fingerprint: fp_abc123 ip: 1.2.3.4 language: en-GB items: - name: Calabash Pipe price: 2500 product_type: physical quantity: 1 sku: PIPE-001 metadata: channel: web shipping: carrier: DHL method: STANDARD transaction: amount: 4900 currency: EUR reference: ord_001 properties: airline: $ref: '#/components/schemas/Airline' backend_options: additionalProperties: type: object description: >- Provider-specific passthrough fields keyed by backend identifier. Not persisted. example: sift: $site_domain: shop.example.com type: object billing: description: Billing address for the transaction properties: address1: example: 96 Powers Street type: string address2: type: string city: example: Milford type: string country: example: US type: string email: example: test@example.com type: string first_name: example: James type: string last_name: example: Smith type: string phone: example: '7606160717' type: string postal_code: example: '03055' type: string state: example: NH type: string type: object context: description: Ruleset context key. Defaults to "default" if omitted. example: checkout type: string credential: properties: masked_pan: description: Masked PAN credential — required when type is "masked_pan" properties: expiry_month: example: 7 maximum: 12 minimum: 1 type: integer expiry_year: description: Four-digit expiry year example: 2029 type: integer first_six: description: First 6 (or 8) digits of the PAN (BIN/IIN) example: '411111' type: string last_four: description: Last 4 digits of the PAN example: '1111' type: string scheme: description: Card scheme — derived from BIN if omitted example: visa type: string required: - first_six - last_four type: object pan: description: Full PAN credential — required when type is "pan" properties: cardholder_name: description: Name as printed on the card example: Sherlock Holmes type: string expiry_month: example: 7 maximum: 12 minimum: 1 type: integer expiry_year: description: Four-digit expiry year example: 2029 type: integer scheme: description: Card scheme (optional) example: visa type: string value: description: >- Full PAN — never persisted, only the HMAC-SHA256 fingerprint is stored example: '4111111111111111' type: string required: - value - expiry_month - expiry_year type: object sepa: description: SEPA direct debit credential — required when type is "sepa" properties: iban: description: >- Account IBAN — never persisted, only the fingerprint is stored example: DE89370400440532013000 type: string owner_name: description: Account holder name example: John Doe type: string required: - iban - owner_name type: object type: description: Credential type enum: - pan - masked_pan - sepa type: string required: - type type: object customer: properties: id: description: Stable merchant-assigned customer identifier example: cust_001 type: string date_of_birth: description: ISO 8601 date example: '1854-01-06' type: string email: example: sherlock.holmes@example.com type: string first_name: example: Sherlock type: string last_name: example: Holmes type: string name: example: Sherlock Holmes type: string phone: example: '02031234321' type: string registration_time: description: ISO 8601 datetime example: '2024-01-15T10:00:00Z' type: string required: - id type: object device: properties: fingerprint: example: fp_abc123 type: string ip: example: 1.2.3.4 type: string language: example: en-GB type: string session_id: type: string user_agent: type: string type: object items: description: Cart / order line items items: $ref: '#/components/schemas/Item' type: array metadata: additionalProperties: type: string description: >- Flat key-value pairs stored alongside the decision. Available to rules. Not sent to backends. example: campaign: spring_2026 channel: web type: object shipping: description: Shipping address for the transaction properties: address1: example: 96 Powers Street type: string address2: type: string address3: type: string carrier: example: DHL type: string city: example: Milford type: string country: example: US type: string destination_code: type: string destination_types: type: string first_name: example: James type: string last_name: example: Smith type: string method: type: string middle_name: type: string phone: example: '7606160717' type: string postal_code: example: '03055' type: string state: example: NH type: string type: object transaction: properties: amount: description: Amount in minor currency units example: 4900 type: integer currency: description: ISO 4217 currency code example: EUR type: string reference: description: Merchant order or transaction reference example: ord_001 type: string required: - reference - amount - currency type: object required: - credential - customer - transaction title: DecisionRequest type: object DecisionResponse: description: Result of evaluating a transaction against the active ruleset. properties: id: description: Unique decision identifier format: uuid type: string amount: type: - integer - 'null' backend_results: description: One entry per backend rule that was executed. items: $ref: '#/components/schemas/BackendResult' type: array context: example: checkout type: string credential_fingerprint: description: Deterministic HMAC-SHA256 card instrument identifier example: crd_4ba218... type: string credential_type: description: Type of credential supplied in the request enum: - pan - masked_pan - sepa type: - string - 'null' currency: type: - string - 'null' customer_id: type: - string - 'null' decision: description: >- BLOCK terminates on first match. REVIEW accumulates. ALLOW is the default when no rules match. enum: - ALLOW - BLOCK - REVIEW - PROVISIONAL type: string device_fingerprint: type: - string - 'null' device_ip: type: - string - 'null' evaluated_at: format: date-time type: string events: description: Always empty on a freshly evaluated decision. items: properties: id: format: uuid type: string occurred_at: format: date-time type: string processed_at: format: date-time type: string type: enum: - authorization - capture - refund - void - chargeback - fraud_report - failed type: string type: object type: array has_backend_error: description: >- True if any backend_results entry carries a non-nil error (e.g. "backend_capability_disabled"). type: boolean integration: description: Integration type that originated this decision (e.g. 'interceptor') type: - string - 'null' interceptor_id: description: ID of the interceptor that originated this decision format: uuid type: - string - 'null' latency_us: example: 4250 type: integer masked_credential: description: Display-safe masked representation, e.g. '411111 ****** 4242' example: 411111 ****** 4242 type: - string - 'null' metadata: additionalProperties: type: string description: Merchant-supplied key-value pairs stored with the decision. type: - object - 'null' resolution: description: Always null on a freshly evaluated decision. properties: action: enum: - ACCEPTED - REJECTED type: string resolved_at: format: date-time type: string type: - object - 'null' ruleset_id: format: uuid type: - string - 'null' ruleset_version: type: - integer - 'null' source: description: >- RULE_ENGINE — condition rules only. BACKEND — backend rule(s) only. COMBINED — both. enum: - RULE_ENGINE - BACKEND - COMBINED type: string transaction_reference: type: - string - 'null' triggered_rules: items: $ref: '#/components/schemas/TriggeredRule' type: array title: DecisionResponse type: object Unauthorized: description: No valid authentication was provided. example: classifier: UNAUTHORIZED code: 401 message: No valid means of authentication was provided properties: classifier: enum: - UNAUTHORIZED type: string code: enum: - 401 type: integer message: type: string required: - classifier - code - message title: Unauthorized type: object Forbidden: description: The token lacks the scope required for this operation. example: classifier: FORBIDDEN code: 403 message: Not allowed to access this resource or feature properties: classifier: enum: - FORBIDDEN type: string code: enum: - 403 type: integer message: type: string required: - classifier - code - message title: Forbidden type: object ValidationErrors: description: Response shape for request validation failures example: classifier: VALIDATION_ERROR code: 422 validation_errors: - message: must be a positive integer path: limit properties: classifier: example: VALIDATION_ERROR type: string code: example: 422 type: integer validation_errors: items: properties: message: example: must be a positive integer type: string path: example: limit type: string type: object type: array required: - classifier - code - validation_errors title: ValidationErrors type: object Airline: description: Airline / travel industry data. Present only for airline transactions. properties: booking_code: description: PNR / booking reference example: X36Q9C type: string issuing_carrier: description: IATA carrier code example: LH type: string legs: items: properties: arrival_airport: description: IATA airport code type: string arrival_at: description: ISO 8601 datetime type: string carrier_code: description: IATA carrier code type: string departure_airport: description: IATA airport code type: string departure_at: description: ISO 8601 datetime type: string fare_amount: description: Fare in minor currency units type: integer flight_class: description: Booking class (e.g. Y, J, F) type: string flight_number: type: string route_type: enum: - one_way - round_trip - multi_city type: string stop_over: type: boolean type: object type: array passengers: items: properties: country_code: description: ISO 3166-1 alpha-2 type: string date_of_birth: description: ISO 8601 date type: string email: type: string first_name: type: string frequent_flyer_number: type: string last_name: type: string phone: type: string ticket_number: type: string type: object type: array restricted_ticket: description: Whether the ticket is non-refundable type: boolean ticket_number: example: 220-1234567890 type: string travel_agency_code: description: Travel agency IATA code type: string travel_agency_name: type: string title: Airline type: object Item: description: A cart / order line item example: categories: - Accessories - Smoking name: Calabash Pipe price: 2500 product_type: physical quantity: 1 sku: PIPE-001 properties: categories: description: Product category hierarchy example: - Accessories - Smoking items: type: string type: array discount_amount: description: Discount on this line item in minor currency units example: 0 type: integer name: description: Product name example: Calabash Pipe type: string price: description: Unit price in minor currency units example: 2500 type: integer product_type: description: Product type — critical fraud signal enum: - physical - digital - service example: physical type: string product_url: description: URL to the product page example: https://shop.example.com/pipe-001 type: string quantity: description: Quantity ordered example: 1 type: integer sku: description: Product SKU example: PIPE-001 type: string tax_amount: description: Tax on this line item in minor currency units example: 0 type: integer upc: description: Universal Product Code type: string title: Item type: object BackendResult: description: Outcome of a single backend rule that was executed. properties: backend: type: string decision: enum: - ALLOW - BLOCK - REVIEW type: - string - 'null' error: description: >- Error code when the backend did not produce a decision. "insufficient_context" means required context fields were missing and no call was made. type: - string - 'null' latency_ms: type: integer link_execution_id: description: >- Execution ID from the Link integration. Present only for Link-backed backends. type: - string - 'null' link_timing: description: >- Server-Timing breakdown in milliseconds, parsed from the backend response. Present only for Link-backed backends. properties: external: type: number internal: type: number total: type: number type: - object - 'null' live: description: Whether the backend ran live (true) or in shadow mode (false). type: boolean missing_fields: description: >- Dot-notation paths of required context fields that were absent. Populated only when error is "insufficient_context". items: type: string type: - array - 'null' raw_response: type: - object - 'null' rule_id: type: string title: BackendResult type: object TriggeredRule: properties: action: enum: - BLOCK - REVIEW example: BLOCK type: - string - 'null' name: example: Block USD type: - string - 'null' rule_id: example: r1 type: string type: enum: - condition - blacklist - backend - backend_group example: condition type: string title: TriggeredRule type: object securitySchemes: bearerAuth: bearerFormat: JWT description: >- HS256-signed JWT bearer token, obtained via the OAuth2 client-credentials grant (see Authentication). scheme: bearer type: http ````