Skip to main content
This integration is currently in preview and subject to change.
This guide shows you how to detect and handle challenges that require customer authentication or verification before a transaction can continue.

​
Prerequisites

  • A connected customer.
  • 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. You most commonly see challenges when you:
  • Request an executable quote and the customer needs to upgrade authentication or limits.
  • Execute a transaction and the customer needs to complete additional authentication or verification (for example, Strong Customer Authentication / 3D Secure or identity verification).

​
Where challenges show up

Challenges are returned as part of API or SDK results. For example, an executable quote may include a challenge field:
Example challenge payload
{
  "id": "cV8wMDE=",
  "signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2029-07-21T17:32:28Z",
  "challenge": {
    "kind": "frame",
    "id": "ch_123e4567-e89b-12d3-a456-426614174000"
  }
}

​
How to handle a challenge

  1. Detect the challenge: If a result includes a challenge, treat the current action as blocked until the challenge completes.
  2. Render the challenge UI:
    • If the challenge is a frame challenge (kind: "frame"), render a dedicated frame (WebView on mobile, iframe on web) and handle events the same way you do for other frames.
    • If the challenge is a first-party challenge, the SDK/API response includes instructions for how to proceed.
  3. Retry the original action: Once the challenge completes successfully, request a new executable quote (if needed) and continue the flow.

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