Integration Patterns
A Firmly integration is a combination of choices across four phases. Every implementation picks one option per phase. Authentication is always required. Cart orchestration and order placement on the merchant’s platform always go through Firmly.
This page is the matrix view — pick one option per phase and you have your integration shape. For a deep dive on the most common axis of choice (where the checkout UI lives), see the Hosted, Embedded, and Deep Link / Headless sub-pages.
The four phases
| Phase | Option | Description |
|---|---|---|
| Hosting | A — Partner-Hosted | Partner hosts the experience on their own infrastructure |
| B — Firmly-Hosted PoC (UAT) | Firmly hosts everything in UAT, zero-trust email authentication, data removed after PoC | |
| Authentication | A — S2S Tokens | Partner server creates device_id, signs with S2S token |
| B — Browser Sessions | User’s browser connects directly, Firmly generates device_id |
|
| Discovery | A — Merchant Catalog | Firmly feeds catalog, partner pre-loads and serves |
| B — Catalog Full-text Search | Partner calls Firmly’s search API at runtime | |
| C — Partner’s Own Catalog | Partner uses own catalog; Firmly not involved in discovery | |
| Checkout | A — Real-time | Partner UI collects guest credit card; Firmly tokenizes and places order via sync API |
| B — Async (VCC) | Partner takes full order + own payment; sends VCC to Firmly for merchant placement | |
| C — Firmly Checkout UI | Partner hands off; Firmly overlay/dropin handles checkout end-to-end |
Partner integration examples
What varies most across partners is who owns discovery and who owns the checkout UI.
| Partner profile | Authentication | Discovery | Checkout |
|---|---|---|---|
| Greenfield — no catalog, no checkout UI | A or B | A or B | C (Firmly UI) |
| Has own catalog and search — no checkout UI | A or B | C (own catalog) | C (Firmly UI) |
| Has own catalog, search, and checkout UI | A or B | C (own catalog) | A (real-time, guest CC) |
| Has own catalog, search, checkout UI, and own payment | A or B | C (own catalog) | B (async, VCC) |
Each row is a valid integration shape. Most destinations fall into one of these four profiles. All four profiles assume Hosting Option A (Partner-Hosted); the Firmly-Hosted PoC option is used for UAT rather than a production profile.
Where the checkout UI lives — the most common decision
The Checkout phase has three options (A, B, C above). Each gets its own dedicated page with details on URLs, parameters, and code:
Comparison — checkout UI sub-options
| Hosted (C) | Embedded (C, iframe) | Deep Link / Headless (A or B) | |
|---|---|---|---|
| Where checkout UI lives | Firmly-hosted page | Inside partner surface, Firmly-rendered | Inside partner surface, partner-rendered |
| UI control | Low | High (chrome around iframe) | Total |
| PCI scope on partner side | None (Firmly handles) | Reduced (iframe) | Higher (depending on payment flow) |
| Best for | First integration, low-touch surfaces | Mature surfaces wanting branded UX | Voice, conversational, fully autonomous flows |
Build your integration — the API call order
Whichever combination of phases you pick, every flow goes through the same Firmly APIs underneath. The list below is the order of operations for a complete purchase. Click any item to jump to the canonical reference.
1. Authenticate
- Authentication overview — pick the pattern
- Browser session — Auth Option B
- Server-to-server — Auth Option A
2. Discover products (if Discovery Option A or B)
- Discovery overview
- Search — Discovery Option B
- Catalog list — Discovery Option A
- Get product
- Get product from URL
(Skip this phase if Discovery Option C — partner uses own catalog.)
3. Build the cart
- Cart management overview
- Get cart
- Add line item
- Update line item
- Clear cart
- Add promo codes
- Add addon
4. Set shipping
- Checkout overview
- Set shipping info
- Get shipping availability
- Set shipping method
- Set fulfillment type
For multi-shipment carts, see Shipping and Fulfillment.
5. Collect consents and billing
How consent fits into an agentic flow is covered in Consent & Disclosure.
6. Pay and place the order
Card flows encrypt the card client-side with Firmly’s public key, then submit. Express options follow their own sequence — Klarna is documented below; PayPal and Click to Pay require coordination with Firmly for the provider-specific sequence.
- Get payment public key
- Place order (v2)
- Complete order (v2)
- Klarna express — start
- Klarna express — authorize
- Klarna express — complete order
- PayPal express — start
- PayPal express — authorize
- PayPal express — complete order
Errors & recovery
Any call above can return a recoverable error. The canonical catalog and recovery patterns:
Protocol vs. integration pattern
The four phases describe where each piece of the integration lives. They’re independent of which protocol the destination uses to talk to Firmly (UCP, MCP, ACP, or direct REST). Any protocol can be combined with any phase-option combination.
See Protocols for the protocol comparison.
End-to-end runnable example
If you’d rather read code than narrative, the Advanced Checkout Guide is the full sequence above as a runnable Node script — start there, then return to this page for the pattern-level guidance and the per-endpoint references.