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.

The Challenge frame handles all verification steps required to complete a card transaction. The URL is provided by the buy frame’s challenge event — do not construct it yourself. The frame is self-driving: after the handshake, there are no further parent-to-child messages. It sequences through all required verification steps, creates the transaction, and emits complete when the pipeline finishes.

​
URL

Provided by the buy frame’s challenge event payload. Do not modify it.

​
Requirements

​
Size

Render the frame in a modal or full sheet so the customer can complete verification. The frame adapts to any size, but a full-screen or large modal works best for flows like 3D Secure that load bank-hosted pages.

​
Initialization parameters

PropertyTypeRequiredDescription
clientTokenstring✅Included automatically in the challenge URL for CSP compliance. Do not remove it.
channelIdstring✅Generate a fresh channel ID on your side and append it to the challenge URL before setting it as the frame src.
challengeTokenstring✅Opaque token. Do not modify or parse it.

​
Events

All events are dispatched using the message pattern described in the frames protocol. Below are the event payloads specific to the Challenge frame.

​
Outbound events

frame->parent These events are sent from this frame to the parent window.

​
handshake

The frame requests that you open a message channel. 
{
  "version": 2,
  "meta": { "channelId": "ch_challenge_1" },
  "kind": "handshake"
}

​
ready

The challenge UI is rendered and visible to the customer. 
{
  "version": 2,
  "meta": { "channelId": "ch_challenge_1" },
  "kind": "ready"
}

​
complete

All verification steps resolved and the transaction pipeline finished. Remove the challenge frame and the buy frame, then navigate to the confirmation screen. 
{
  "version": 2,
  "meta": { "channelId": "ch_challenge_1" },
  "kind": "complete",
  "payload": {
    "flow": "buy",
    "transaction": {
      "id": "txn_01",
      "status": "pending"
    }
  }
}

​
cancelled

The customer dismissed the challenge. Remove the challenge frame and buy frame, then offer a retry path. 
{
  "version": 2,
  "meta": { "channelId": "ch_challenge_1" },
  "kind": "cancelled",
  "payload": {
    "flow": "buy"
  }
}

​
error

The challenge failed. Remove the challenge frame and buy frame, then surface the message to the developer. 
{
  "version": 2,
  "meta": { "channelId": "ch_challenge_1" },
  "kind": "error",
  "payload": {
    "code": "generic",
    "message": "Challenge failed."
  }
}
CodeDescription
configurationErrorFrame initialization failed
invalidTokenChallenge token is invalid or expired
genericUnspecified error

​
Inbound events

parent->frame

​
ack

Acknowledge the handshake. This is the only message you send to the challenge frame — it is self-driving after the handshake. 
{
  "version": 2,
  "meta": { "channelId": "ch_challenge_1" },
  "kind": "ack"
}