Handle challenges

Detect and respond to challenges.

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

Prerequisites

• An authenticated customer, either connected through the connect flow or logged in through the Auth frame on the Customer API 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 and the Customer API 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.

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.
• The Google Pay frame emits challenge for Google Pay transactions.
• 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 challenge event uses the same envelope across all of the frames:

Example challenge event

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "challenge",
  "payload": {
    "kind": "frame",
    "url": "https://blocks.moonpay.com/platform/v1/challenge?challengeToken=..."
  }
}

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().

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).