Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dev.moonpay.com/llms.txt

Use this file to discover all available pages before exploring further.

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