.png)
Riskified Integration Guide
Connect ecommerce orders and lifecycle events to Riskified through REST APIs and configured callback endpoints.
Riskified integration options at a glance
Riskified primarily integrates through HTTPS REST APIs for submitting orders, obtaining risk decisions, and sending fulfillment, cancellation, refund, and chargeback updates. Riskified also supports callback-style notifications for selected decisions and lifecycle events, although coverage depends on the merchant configuration and event type. API requests use a merchant-specific access token in the X-Access-Token header. Martini can consume these REST endpoints, protect credentials in secrets, transform ecommerce payloads, expose callback endpoints, and orchestrate downstream workflows. A general-purpose bulk API, file interface, GraphQL API, SOAP API, and direct database access were not confirmed, so high-volume processing should use controlled Martini scheduling, queueing, retries, and rate-aware orchestration.
| Integration point | Supported by Riskified? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Submit orders for risk evaluation and send fulfillment, cancellation, refund, and chargeback lifecycle updates. | Martini can consume Riskified HTTPS REST endpoints, map request and response payloads, apply business rules, and orchestrate downstream actions. |
| Webhooks / outbound callbacks | Limited | Receive selected Riskified decisions and order lifecycle notifications through merchant-configured callback mechanisms. | Martini can expose an HTTP API endpoint or webhook-triggered workflow, validate notifications, correlate orders, and update downstream systems. |
| Authentication | Yes | Authenticate Riskified API requests with a merchant-specific access token in the X-Access-Token header over HTTPS. | Martini stores the token in protected secrets or environment configuration and adds it to outbound requests without exposing it in logs or responses. |
| Bulk / async / batch APIs | Not confirmed | A general-purpose Riskified bulk API was not confirmed. High-volume processing should use controlled orchestration unless Riskified confirms a merchant-specific capability. | Martini can schedule workflows, control concurrency, queue work, and retry transient failures without assuming a native bulk endpoint. |
| File / attachment APIs | Not confirmed | No dedicated Riskified file or attachment API was confirmed; integrations should use structured API payloads. | Martini can process files on the merchant side when required, but should not assume that files can be uploaded to Riskified. |
| Database / analytics access | Not confirmed | No direct Riskified database, JDBC, or database analytics interface was confirmed. | Martini can read approved merchant-side operational data and write normalized results to an approved database or analytics platform. |
How Riskified exposes data and business events
Riskified REST APIs
Riskified’s primary integration model uses HTTPS REST requests to submit orders for evaluation and communicate subsequent fulfillment, cancellation, refund, and chargeback updates. Request and response fields can vary by operation and merchant configuration.
Martini implementation pattern
Martini consumes the relevant Riskified endpoint from a workflow, adds the merchant access token through protected configuration, maps the source ecommerce or operational payload, and interprets the response. The workflow can return a normalized decision, persist correlation data, and retry only transient failures.
Implementation sequence
Riskified callbacks
Riskified supports callback-style notifications for selected decisions and order lifecycle events. Event coverage depends on the merchant’s configured integration and the specific event type, so implementations should not assume every event is delivered as a callback.
Martini implementation pattern
Martini exposes a controlled HTTP endpoint and starts a workflow when a supported Riskified notification arrives. The workflow validates the payload and request controls, correlates the notification to an order, applies business rules, updates downstream systems, and records unknown or invalid events for review.
Implementation sequence
Scheduled reconciliation
Riskified’s documented model is primarily transaction- and event-oriented, and a general-purpose bulk API was not confirmed. Scheduled reconciliation can therefore help identify differences between merchant systems and Riskified-related processing state.
Martini implementation pattern
Martini schedules a workflow to read approved merchant-side order and lifecycle data, compare it with stored Riskified request and response state, and route discrepancies for controlled investigation. Any Riskified retrieval operation must be confirmed for the merchant account before use.
Implementation sequence
Common Riskified integration patterns
Pattern 1: Evaluate ecommerce orders
When to use this pattern
Use this pattern when one or more storefronts need a consistent fraud-decision interface before an order proceeds. It separates commerce-specific payloads from Riskified’s request structure and provides explicit handling for approval, decline, pending, timeout, and technical failure states.
Integration direction
Example Mapping
| Riskified Field | Canonical Field | Target Field |
|---|---|---|
| order.id | sourceOrderId | Riskified order identifier |
| customer.email | customerEmail | Riskified customer email |
| lineItems | products | Riskified products |
| shippingAddress | shippingAddress | Riskified shipping data |
Martini implementation pattern
Martini receives an order through an API or workflow trigger, validates and transforms customer, billing, shipping, payment, and product data, then calls Riskified’s REST API. It interprets the response using merchant policy, stores the request and decision correlation identifiers, and returns or publishes a normalized result. Transient failures use bounded retries; malformed requests and business declines are not blindly retried.
Martini capabilities used
- workflows
- API consumption
- data mapping
- business rules
- secrets management
- error handling
Pattern 2: Synchronize order lifecycle events
When to use this pattern
Use this pattern to send fulfillment, cancellation, refund, and chargeback updates from commerce, order-management, payment, or ERP systems to Riskified. It is appropriate when lifecycle events occur after the initial decision and must remain consistent across systems.
Integration direction
Example Mapping
| Riskified Field | Canonical Field | Target Field |
|---|---|---|
| orderId | sourceOrderId | Riskified order identifier |
| fulfillment.status | fulfillmentStatus | Riskified fulfillment operation |
| refund.amount | refundAmount | Riskified refund operation |
| chargeback.reference | disputeReference | Riskified chargeback operation |
Martini implementation pattern
A Martini workflow consumes lifecycle events, validates stable order and event identifiers, maps each event to the corresponding Riskified operation, and records processing state. Composite idempotency keys prevent duplicate updates, while rate-aware scheduling and retry backoff protect the API during high-volume periods. Unsupported or unrecognized event types are routed to an exception path.
Martini capabilities used
- event-driven workflows
- API consumption
- data mapping
- idempotency rules
- retry handling
- audit logging
Pattern 3: Process Riskified callbacks
When to use this pattern
Use this pattern when the merchant has configured Riskified callback-style notifications for selected decisions or lifecycle events and needs to distribute them to commerce, service, ERP, or analytics applications.
Integration direction
Example Mapping
| Riskified Field | Canonical Field | Target Field |
|---|---|---|
| order_id | sourceOrderId | Salesforce order reference |
| decision | riskDecision | Salesforce risk status |
| event_type | lifecycleEventType | Salesforce event classification |
| decision_metadata | riskMetadata | Salesforce integration metadata |
Martini implementation pattern
Martini exposes a protected API endpoint that starts a callback workflow. The workflow validates the notification, correlates it to the source order, applies rules for approved, declined, or updated states, and maps the result to Salesforce or another target. Duplicate notifications are safely acknowledged without repeating irreversible downstream actions, and unknown event types are retained for review.
Martini capabilities used
- API exposure
- workflow triggers
- validation
- data mapping
- business rules
- error handling
Pattern 4: Reconcile Riskified processing state
When to use this pattern
Use this pattern when the merchant needs operational assurance that decisions and lifecycle updates in commerce or ERP systems match the state recorded by the integration. It is especially useful for investigating delayed callbacks, failed requests, and duplicate events.
Integration direction
Example Mapping
| Riskified Field | Canonical Field | Target Field |
|---|---|---|
| order.id | sourceOrderId | Snowflake order key |
| riskDecision | decisionStatus | Snowflake decision status |
| lastLifecycleEvent | lifecycleStatus | Snowflake lifecycle status |
| processingError | integrationException | Snowflake exception detail |
Martini implementation pattern
A scheduled Martini workflow reads approved merchant-side data and stored integration state, compares normalized order and lifecycle values, and writes reconciliation results to an analytics target or exception queue. Corrective calls are made only through Riskified operations confirmed for the merchant account. Differences are classified, logged, and routed for review rather than silently overwritten.
Martini capabilities used
- scheduled workflows
- data mapping
- database or analytics integration
- business rules
- monitoring
- exception handling
Applications commonly integrated with Riskified
Riskified can be positioned between commerce, order, payment, ERP, customer-service, and analytics applications. The following are practical enterprise architecture patterns; specific packaged integrations and merchant-account capabilities should be verified with Riskified.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Shopify | Submit Shopify orders for Riskified evaluation and synchronize decisions, fulfillment, refunds, and cancellations. | Shopify → Martini → Riskified | Martini receives Shopify order events or API data, maps the order into Riskified’s request structure, calls the Riskified REST API, and routes the decision back to Shopify or an internal order workflow. Lifecycle updates can be sent through separate controlled workflows. |
| Salesforce Commerce Cloud | Apply Riskified decisioning during checkout or order processing and synchronize subsequent order lifecycle events. | Salesforce Commerce Cloud → Martini → Riskified | A Martini API or workflow accepts commerce order data, validates required customer, payment, product, billing, and shipping fields, calls Riskified, and returns a normalized decision response. Fulfillment and refund updates are processed asynchronously. |
| Adobe Commerce | Evaluate orders and return fraud outcomes to the commerce order workflow. | Adobe Commerce → Martini → Riskified | Martini consumes Adobe Commerce order payloads, applies field and business-rule transformations, invokes Riskified with the protected access token, and publishes the decision or an exception result to the commerce process. |
| BigCommerce | Send storefront orders to Riskified and propagate risk decisions back to order processing. | BigCommerce → Martini → Riskified | A workflow receives or retrieves BigCommerce orders, builds the Riskified order request, handles synchronous success, pending, timeout, and retryable outcomes, and records correlation identifiers for later lifecycle updates. |
| SAP Commerce Cloud | Connect enterprise order processing with Riskified decisioning and fulfillment, refund, cancellation, and chargeback updates. | SAP Commerce Cloud → Martini → Riskified | Martini provides an orchestration layer between SAP Commerce Cloud and Riskified, normalizing order identifiers and lifecycle events while applying idempotency, retry, and exception-routing rules. |
| NetSuite | Synchronize approved orders, fulfillment, refunds, and chargeback-related information with ERP and financial processes. | NetSuite → Martini → Riskified | Martini coordinates NetSuite order and financial events with Riskified requests, stores processing state, and maps Riskified outcomes to ERP status fields without treating business declines as technical failures. |
| Salesforce | Make Riskified decisions and order-risk status available to service and operations teams. | Riskified → Martini → Salesforce | Martini receives supported Riskified callbacks, correlates them with orders, transforms decision and lifecycle data into Salesforce objects, and routes unknown event types to an observable exception workflow. |
| Snowflake | Consolidate order, decision, fulfillment, refund, and chargeback information for reporting and risk analysis. | Riskified → Martini → Snowflake | Martini normalizes approved operational data and Riskified responses into analytics-ready structures, applies privacy and retention rules, and writes governed records to Snowflake through the merchant’s approved data-access pattern. |
How to build a Riskified integration in Martini
Objective
Configure the Riskified merchant endpoint and access token for each Martini environment without embedding credentials in workflow definitions.
Instructions in Martini
- Store the X-Access-Token value in Martini secrets or protected environment configuration.
- Configure merchant-specific base URLs and callback settings separately for development, testing, and production.
- Confirm enabled Riskified operations and endpoint permissions with the merchant account.
Objective
Select an event, API request, or schedule that matches the required integration behavior.
Instructions in Martini
- Use an API or application event for synchronous order evaluation.
- Use callback-triggered workflows for supported Riskified notifications.
- Use scheduled workflows for controlled lifecycle processing or reconciliation.
Objective
Acquire the order, decision, or lifecycle data required by the workflow.
Instructions in Martini
- Receive source orders and lifecycle events from the commerce or operational application.
- Receive Riskified callbacks through a protected Martini API endpoint when configured.
- Retrieve merchant-side state for reconciliation using approved systems and endpoints.
Objective
Coordinate the Riskified call, callback processing, downstream updates, and state management as an end-to-end workflow.
Instructions in Martini
- Separate synchronous decision processing from asynchronous lifecycle updates.
- Persist source identifiers and Riskified correlation data.
- Use controlled concurrency and queueing for high-volume workloads.
Objective
Convert source application payloads into Riskified structures and normalize Riskified responses for downstream consumers.
Instructions in Martini
- Map customer, billing, shipping, payment, product, and transaction fields explicitly.
- Preserve stable order identifiers across all requests and callbacks.
- Version mappings when merchant schemas or event types change.
Objective
Ensure decisions, pending states, lifecycle events, and exceptions are handled according to merchant policy.
Instructions in Martini
- Do not treat timeouts automatically as approvals or declines.
- Distinguish business-level declines from authentication, validation, rate-limit, and server errors.
- Route unknown event types and conflicting states to controlled review.
Common Riskified data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Order | Transaction, customer, payment, product, shipping, and billing information submitted for risk evaluation. | Shopify, Salesforce Commerce Cloud, Adobe Commerce, BigCommerce, SAP Commerce Cloud, NetSuite | Martini validates and maps source order data, preserves the merchant order identifier, removes unnecessary sensitive fields, and submits the resulting REST payload. |
| Decision | Riskified’s approval, decline, or other decision metadata for an order. | Commerce platforms, order-management systems, Salesforce, NetSuite | Martini normalizes the decision, handles pending and timeout states according to merchant policy, and routes the result to the appropriate downstream workflow. |
| Fulfillment | Notification that an approved order or order line has shipped or otherwise been fulfilled. | Riskified, commerce platforms, NetSuite, Snowflake | Martini maps shipment and order identifiers, sends the corresponding lifecycle update, and prevents duplicate processing. |
| Cancellation | Notification that an order or order line was canceled. | Riskified, commerce platforms, NetSuite, Salesforce | Martini transforms cancellation details, applies event-ordering and idempotency rules, and records the request outcome. |
| Refund | Notification that money was returned to the customer for an order or order line. | Riskified, payment and commerce systems, NetSuite, Snowflake | Martini validates refund references and amounts, sends the supported Riskified operation, and separates validation failures from retryable transport errors. |
| Chargeback | Notification that a payment dispute or chargeback was received for an order. | Riskified, payment systems, NetSuite, Salesforce, Snowflake | Martini correlates the chargeback with the source order, maps dispute information, stores an audit trail, and routes exceptions for investigation. |
Authentication and security considerations
Token-based API access
Riskified API requests use a merchant-specific access token in the X-Access-Token header over HTTPS. Store the token in Martini secrets or protected environment configuration and keep merchant endpoints environment-specific.
Callback protection
Protect Martini callback endpoints with authentication, network controls, payload validation, correlation checks, and replay protection where supported by the merchant configuration.
Data minimization
- Send only payment and customer data required by the Riskified contract.
- Do not expose access tokens in logs, responses, or exception payloads.
- Apply appropriate retention and access controls to order, decision, and dispute data.
Operational considerations for Riskified integrations
Throughput and rate limits
Confirm applicable Riskified request limits and quotas for the merchant account. Use controlled concurrency, scheduling, queueing, and retry backoff for high-volume order and lifecycle processing.
Pagination and endpoint behavior
Follow the pagination and response fields documented for each enabled endpoint rather than assuming a universal page or cursor model.
Idempotency and timing
Persist processing state before irreversible downstream actions. Handle duplicate callbacks, delayed events, pending decisions, and timeouts explicitly; a timeout should not automatically be interpreted as approval or decline.
Schema and testing
Version transformations as payment methods, shipping fields, decision attributes, or event types evolve. Test with merchant-specific schemas and route unknown fields or event types to an observable exception path.
Why use Martini instead of scripts or point-to-point integrations?
Reusable orchestration
Martini separates commerce-specific payloads from Riskified request structures and provides reusable workflows for order evaluation, lifecycle updates, callbacks, and reconciliation.
Reliable operations
Instead of embedding API calls in point-to-point scripts, Martini centralizes secrets, mappings, business rules, retries, idempotency, monitoring, and exception handling.
Controlled change
Versioned workflows and mappings make it easier to support multiple commerce platforms while preserving consistent Riskified integration behavior and auditability.
API-led architecture
Martini can expose a normalized internal API for downstream applications, consume Riskified REST APIs, and route supported callbacks through governed workflows without requiring a dedicated vendor connector.
Frequently asked questions
Riskified is primarily integrated through HTTPS REST APIs. Merchant systems submit Order data for evaluation, receive a Decision, and send lifecycle updates such as Fulfillment, Cancellation, Refund, and Chargeback. Riskified also supports callback-style notifications for selected events, subject to merchant configuration and event coverage.
Yes. Martini can consume Riskified REST APIs, add the merchant access token through protected configuration, transform ecommerce and operational payloads, expose endpoints for supported callbacks, and orchestrate downstream updates and exception handling.
No. A dedicated Riskified connector is not required. Martini can use Riskified’s documented REST APIs, supported callback mechanisms, and HTTPS authentication model. No native Martini Riskified connector is documented in the supplied materials.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Riskified. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Riskified, cloud infrastructure, or other third-party systems depending on subscriptions, usage, and deployment choices.
Use Riskified’s HTTPS REST APIs for order evaluation and documented lifecycle operations. Use callback-style notifications for selected decisions or events when enabled for the merchant. GraphQL, SOAP, a general-purpose bulk API, file APIs, and direct database access were not confirmed.
Yes, when the relevant Riskified callback configuration is enabled. Martini can expose a protected HTTP endpoint, validate the notification, correlate it to an Order, apply idempotency rules, and update commerce, ERP, service, or analytics systems. Callback coverage should be confirmed for each event type.
Martini maps customer, billing, shipping, payment, product, transaction, and lifecycle fields into Riskified’s operation-specific payloads, then normalizes Decisions and notifications for downstream applications. Stable order identifiers, versioned mappings, and stored correlation data support reliable synchronization.
Martini can classify authentication, validation, rate-limit, transient server, and business-level outcomes separately. Transient failures can use bounded exponential backoff and controlled concurrency, while malformed requests and business decisions should not be blindly retried. Duplicate callbacks and lifecycle events should be protected with idempotency keys based on event identifiers or stable order and event attributes.
Related Martini documentation
Riskified APIs
Connect Riskified with your enterprise systems
Use Martini to orchestrate Riskified REST API calls, process supported callbacks, synchronize order lifecycle data, and apply reliable enterprise integration controls.