Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. API Reference
  3. Agentic Pay
  4. Iframe Callback

Iframe Callback

GET https://api.firmly.work/api/v1/wallets/agentic-pay/iframe-callback

​​ Overview

GET https://api.firmly.work/api/v1/wallets/agentic-pay/iframe-callback

Returns an HTML page that acts as a postMessage bridge for Agentic Pay iframe flows. When a network iframe completes a FIDO ceremony or authentication challenge, it redirects to this callback URL with the result encoded in query parameters. The page decodes the result and relays it to the parent window via postMessage.

​​ Authentication

This endpoint requires no authentication.

​​ Query Parameters

These parameters are set by the network iframe redirect, not by the destination.

  • origin (string) — The origin this callback page will postMessage its result to. It must match a Firmly domain pattern (https://*.firmly.work in the sandbox) — this page is a Firmly-hosted bridge, not the partner’s own page.
  • res (string) — Base64-encoded JSON result from the network iframe containing the verification outcome.

​​ Response

The response is an HTML page (content-type: text/html) that performs the following steps:

  1. Validates the origin parameter against Firmly’s domain allowlist
  2. Decodes the base64 res parameter
  3. Posts { type: 'agentic_pay_callback', result: decoded } to the parent window via postMessage
  4. On error, posts { type: 'agentic_pay_error', error: errorMessage } instead

​​ How It Fits in the Flow

This endpoint is typically used as the callback_uri parameter when triggering enrollment or intent challenges:

​​ Destination Triggers Challenge

The destination calls /enroll/trigger (enrollment) or /intent (payment), which returns a verification URI for an iframe. (/intent/challenge consumes the iframe result — it does not hand out the URI.)

​​ Network Iframe Loads

The cardholder completes the FIDO ceremony, 3DS challenge, or iframe handshake inside the network iframe.

​​ Redirect to Callback

The network iframe redirects to this /iframe-callback endpoint with the result in query parameters.

​​ postMessage to Parent

The callback page decodes the result and sends it to the parent window via postMessage.

​​ Parent Captures Result

The parent window receives the message and forwards the result to the next API call (e.g., /enroll/verify).

  • Trigger Enrollment — Returns the enrollment verification URI that may use this callback
  • Create Intent — Returns the payment verification URI that may use this callback
  • Intent Challenge — Consumes the iframe result relayed by this callback