Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. Solutions
  3. ...
  4. Use Cases
  5. Smart Payment Selection Agent

Smart Payment Selection Agent

The user reaches checkout and the agent picks the best payment method given the user’s preferences and the cart context: a fresh card, an express wallet (Google Pay, PayPal, Click to Pay), Buy Now Pay Later (Klarna), a saved card, or Agentic Pay for autonomous purchases. The agent then runs the right sequence for the chosen path.

This scenario covers the breadth of Firmly’s payment surface in one flow. It’s a strong fit for any destination that wants to differentiate on a frictionless payment experience.

Choice Default Why
Integration pattern Deep Link / Headless for full control; Embedded for native UI Express wallets need a UI handoff (wallet sheets) — embedded covers that for free
Protocol Direct REST Payment paths are payment-specific; protocol doesn’t change the sequence

​​ Payment paths

Firmly supports five payment paths. The agent picks based on what the cart returns in payment_method_options.

​​ Path A — Card via encrypted JWE

# Endpoint Purpose
1 Get payment public key RSA public key
2 (client-side) JWE-encrypt the card Local — no network call
3 Complete order (v2) Submit encrypted_card and finalize the existing cart

​​ Path B — Express wallet (Google Pay / PayPal / Click to Pay)

Express wallets carry their own authentication and tokenization. If you use the dropin (hosted or embedded), it handles the wallet sheet and runs the sequence below for you:

  • See Hosted checkout or Embedded checkout for the wallet handoff
  • After the wallet authorizes, order completion returns the finalized cart just like Path A, but with a wallet-tokenized payment reference instead of encrypted_card

To run a wallet headlessly (no dropin), call the express-checkout endpoints directly. They are served from api.firmly.work at /api/v1/domains/{domain}/express/{gateway}/… — a different host from the card Complete Order endpoint. The sequence differs per wallet.

Google Pay — single step. No start or authorize call; place the order directly with the credentials from the Google Pay SDK.

# Endpoint Purpose
1 Complete order — Google Pay Place the order with the Google Pay credentials

Google Pay accepts three credential shapes (Aurus Pay references, the token flow, or the Braintree nonce flow) depending on the merchant’s processor: a single google_pay_token (Stripe, Adyen) or a Braintree nonce with email and google_pay_address. Send exactly one shape.

PayPal — start → authorize → complete-order. PayPal uses the same three-step express-checkout shape as Klarna (Path C), on the /express/paypal/… paths: create the session, confirm the buyer’s paypal_token and payer_id, then place the order. As with Klarna, complete-order authorizes on its own if you pass the token and skip the explicit authorize step.

# Call Purpose
1 Start PayPal Open the PayPal session and get the EC token
2 Authorize PayPal Record the buyer’s approval (paypal_token + payer_id) — optional; step 3 authorizes on its own
3 Complete order — PayPal Place the order and charge the buyer

Click to Pay is not one of the express-checkout gateways (which cover Google Pay, PayPal, and Klarna). Click-to-Pay-style wallet credentials complete through Wallet Complete Order instead — the same endpoint the Agentic Pay path uses (see Path E).

​​ Path C — Klarna BNPL (pay in 4)

# Endpoint Purpose
1 Start Klarna Initialize the BNPL session
2 Authorize Klarna User confirms terms; Klarna returns authorization
3 Complete order — Klarna Place the order against the merchant

​​ Path D — Saved card (reused via Agentic Pay)

When the user has a card they’ve used before, the agent reuses it without re-collecting the PAN. Saved-card reuse runs through Agentic Pay: the card is enrolled once while the cardholder is present, and each later purchase calls Select Card to reference the enrolled virtual_card_id — no fresh public key, no PAN re-entry.

​​ Path E — Agentic Pay (network-token-routed)

For autonomous agent purchasing (the user authorized the agent to buy without being present at transaction time) or biometric / passkey confirmation per purchase, use the Agentic Pay flow. The cardholder enrolls once via Firmly’s Network Token Router; each subsequent payment runs select-card → intent → complete against the user’s virtual_card_id, with mandate-based spending limits enforced at the network level.

Enrollment is a one-time step (cardholder present):

# Endpoint Purpose
1 Enroll One-time card enrollment via the Network Token Router

Each payment then runs:

# Endpoint Purpose
1 Select Card Resolve the user’s stored virtual_card_id — no PAN re-entry
2 Create Intent Authorize a specific payment intent (with mandate limits if autonomous)
3 Wallet Complete Order Place the order against the merchant

See the Agentic Pay Integration Guide for the full sequence, including the iframe handshake and OTP/FIDO verification paths.

​​ Agent decision logic

A simple decision tree the agent can apply:


if agent_acting_autonomously or biometric_per_purchase:
    use Path E (Agentic Pay)
else if cart.total < user.bnpl_threshold and klarna_available:
    use Path C (Klarna)
else if user.has_google_pay or user.has_paypal or user.has_click_to_pay:
    use Path B (express wallet)
else if user.has_saved_card:
    use Path D (saved card)
else:
    use Path A (fresh card via JWE)

The destination owns this decision logic. Firmly executes whichever path is chosen.