Overview

Composer is Spreedly's unified payment and fraud orchestration platform, built by combining the Dodgeball logic engine with Spreedly's existing Composer product. With the addition of transaction processing in the fall 2026 release, Composer becomes a full transaction engine: customers can execute authorizations, captures, retries, and refunds natively within visual workflows without maintaining custom server-side gateway code.

Who is this guide for?

Merchants currently using Spreedly Composer (legacy) - making requests to /transactions and using the workflow canvas for routing rules. These customers have Spreedly environments, vaulted payment methods, and gateway connections already in place.

What changes in Composer 2.0?

• Composer 2.0 introduces transaction processing nodes in the workflow canvas, replacing any remaining server-side gateway API calls. Once a transaction enters the workflow, the platform handles routing, gateway execution, and response handling end-to-end.
• Composer (legacy) will continue to work. No new features will be developed for it after the fall 2026 launch. Migration timeline is customer-controlled; Composer (legacy) end of life date is TBD.
• workflow_key is removed: Composer 2.0 does not use a workflow_key. Workflow selection is handled by the platform based on the environment. Customers should remove this field from their requests as part of migration.
• SDK requirements:
  • The new Composer (Dodgeball) SDK (Server & Client).
  • A payment method collection method - Checkout Headless or Express, or the JavaScript API (this is required alongside the server SDK; PM collection is not included in it). Please note that legacy iFrame is also supported but it is a deprecated product. Implementation steps assume this has already been implemented.

Implementation steps

Phase 1 - Pre-migration assessment

1. Inventory active Composer (legacy) workflows in app.spreedly.com/workflows. Note which handle routing rules, Recover (soft-decline retry), and any conditional logic.
2. Identify any server-side gateway calls happening outside of Composer — for example, direct calls to /v1/gateways/{token}/purchase after Composer returned a routing decision. These are the primary targets for migration to Composer 2.0 transaction processing nodes.
3. Confirm gateway credentials are current and fully provisioned in Connect. Composer 2.0 transaction processing uses credentials configured in the UI; no credentials are passed in the API request.

Phase 2 - SDK setup

4. Install the Composer Server SDK on your backend — required to call Checkpoints and execute transactions.
5. Install the Composer Client SDK on your frontend if you need client-side checkpoint verifications.

Phase 3 - Access Composer 2.0

6. Composer 2.0 is available to all Spreedly accounts. To access it: log in to app.spreedly.com, navigate to the Composer item in the main navigation menu, and click the "Launch Platform" redirect link.
7. Create a sandbox workflow in Composer 2.0 to test before touching production. Sandbox gateway credentials should mirror production configurations.

Phase 4 - Rebuild workflows in the Composer 2.0 canvas

8. Using the visual workflow canvas, recreate your existing routing logic. The canvas supports transaction processing (including split-volume routing, conditional routing rules, and recover), fraud, and 3DS.
9. Add transaction processing nodes to replace server-side gateway calls. Gateway credential assignment and transaction type (Authorize, Capture, or Auth-then-Capture) are configured in the canvas. Response branching — approve, soft decline, hard decline — is also set up in the canvas.
10. For customers using Composer (legacy) Recover: Outage and Standard modes are both supported in Composer 2.0. Reusable Recover configurations from legacy Composer are not carried over, but custom error codes can be added directly to Retry nodes.

Phase 5 - API changes

11. Composer (legacy) used the /transactions endpoint; Composer 2.0 requires adding transaction data to your SDK. The required transaction fields remain: payment_method_token, amount, and currency_code. View/copy expected data from your workflow to input into the SDK. workflow_key and workflow_version will no longer be present in the response.
12. Remove server-side gateway-direct calls (e.g., /v1/gateways/{token}/purchase) once transaction processing nodes are active in the workflow. The workflow now handles gateway execution end-to-end.

Phase 6 - Testing and go-live

13. Test in sandbox using Spreedly test card data. Validate all workflow branches: approve, soft decline, hard decline, and any retry paths. Validate that gateway credential mapping in the canvas routes to the correct gateway.
14. Parallel execution of Composer (legacy) and 2.0 workflows within a single environment is supported during migration. Workflows built in Composer (legacy) can continue to run transactions via the /transactions endpoint; there is no requirement to remove access to Composer (legacy), and its logic is not being touched.
15. Production cutover: Enable the Composer 2.0 workflow for production traffic. Existing gateway API calls can remain active as a fallback during the transition. Composer (legacy) workflows remain available until a TBD deprecation date.