Skip to main content
This guide shows you how to detect and handle challenges that require customer authentication or verification before MoonPay can continue an action.

​
Prerequisites

  • A customer in a payment or onboarding flow: connected through the connect flow, logged in through the Auth frame on the Customer API path, or on the guest checkout path.
  • A UI surface where you can render frames (WebView on mobile, iframe on web).

​
When challenges appear

Challenges are extra steps a customer must complete before MoonPay can continue an action. Common reasons include:
  • Strong Customer Authentication (SCA), for example 3D Secure
  • Identity verification (KYC)
  • Card-specific checks such as CVC re-entry or micro-authorization
Frames, the Customer API, and buy quotes all surface challenges. Frames emit a challenge event that points to the Challenge frame. The Customer API returns a kyc.challenge URL when verification needs a hosted step. A buy quote returns a challenge object when the customer must clear a step before the quote becomes executable.

​
Where challenges are emitted

Each emitting surface hands you a fully-formed URL that you load into the dedicated Challenge frame:
  • The Apple Pay frame emits challenge for Apple Pay transactions, including guest checkout.
  • The Google Pay frame emits challenge for Google Pay transactions, including guest checkout.
  • The buy frame emits challenge for card transactions (see Pay with card).
  • The Customer API returns kyc.challenge ({ url, expiresAt }) on PATCH /customers/{id}/kyc when verification needs a hosted step, and on subsequent GET /customers/{id} responses while the challenge is outstanding. Render the url in the Challenge frame the same way you render a frame-emitted challenge URL. See Handle the hosted challenge.
  • The buy quote returns challenge ({ kind, url }) alongside executable: false when a guest checkout customer can raise their spending limit. This is the only surface that raises a challenge before a payment frame exists, so you resolve it and request the quote again rather than resuming a transaction. See Upgrade a guest account.
On guest checkout, second-factor authentication and KYC step-up both arrive as the same challenge event for Apple Pay and Google Pay. Render the Challenge frame the same way.
The challenge event uses the same envelope across all of the frames. The quote returns the same kind and url fields, without the event wrapper:
Example challenge event

​
How to handle a challenge

  1. Listen for the challenge event on the frame. Treat the action as blocked until the challenge resolves.
  2. Mount the Challenge frame at the URL from the event payload. Pass the URL through as-is — do not construct or modify it. See the Challenge frame reference for the frame URL, parameters, and events.
  3. Handle the Challenge frame events:
    • ready — the challenge UI is rendered and visible.
    • complete — verification resolved. The Challenge frame reports any downstream artifacts (for example, the transaction id and status for the buy flow).
    • cancelled — the customer dismissed the challenge. Offer a retry path.
    • error — the challenge failed. Log the code and message (both are developer-facing and not intended for end-user UI) and show the customer a generic next step, such as retrying or choosing a different payment method.
  4. Tear down the originating frame after complete, cancelled, or error. For the buy frame, call buyResult.value.dispose(). A quote-emitted challenge has no originating frame, so dispose the Challenge frame itself.

​
Implementation tips

  • Use a full-screen surface on mobile: challenge flows often involve authentication or verification, so treat them like a separate screen or full sheet.
  • Validate postMessage events: if you integrate frames manually, validate origin and message shape. The frames protocol documents the shared envelope format.
  • Handle cancellation and timeouts: if the customer closes the challenge or it fails, show a clear next step (retry, choose a different payment method, or exit the flow).