Handle challenges

​

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

• Strong Customer Authentication (SCA), for example 3D Secure
• Identity verification (KYC)
• Card-specific checks such as CVC re-entry or micro-authorization

​

Where challenges are emitted

• The Buy Button frame emits challenge for Apple Pay, Google Pay, card, and bank transfer transactions, including guest checkout and headless mode. See Pay with card and Pay with bank transfer.
• 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.

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "challenge",
  "payload": {
    "kind": "frame",
    "url": "https://platform.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). For the identity flow, check status first: pending or unavailable means the customer isn’t verified. See Pending customers and Unavailable customers.
   • resolved — sent instead of complete only when you opt in with resume. Verification is done and the customer pays on your buy button. See Finish on your buy button.
   • 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. For customer_status_pending or customer_status_unavailable, don’t treat it as a failure: follow Pending customers or Unavailable customers.
4. Tear down the originating frame after complete, cancelled, or error. For the buy button, call buyResult.value.dispose(). A quote-emitted challenge has no originating frame, so dispose the Challenge frame itself.

​

Finish on your buy button

​

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