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.

​
URL

https://blocks.moonpay.com/platform/v1/add-card

​
Requirements

​
Size

Render the frame in a modal or sheet. Width and height are flexible — size the container to fit your UI.
The Add Card frame uses MoonPay’s existing card input UI. A redesign is planned to streamline the experience and explore hosted fields for full design customization.

​
Initialization parameters

PropertyTypeRequiredDescription
clientTokenstring✅The client token returned from the connect flow.
channelIdstring✅A unique identifier for the frame generated on your client. This value is attached to each postMessage payload to help identify messages.

The format of this string is up to you.

​
Events

All events are dispatched using the message pattern described in the frames protocol. Below are the event payloads specific to the Add Card 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_1" },
  "kind": "handshake"
}

​
ready

The frame finished loading and the card input UI is fully rendered. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ready"
}

​
complete

The card was added successfully. Use card.id to get a quote without re-fetching payment methods. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "complete",
  "payload": {
    "card": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "card",
      "cardType": "credit",
      "brand": "visa",
      "last4": "4242",
      "expirationMonth": "12",
      "expirationYear": "2027",
      "availability": { "active": true }
    }
  }
}

​
error

An error occurred during card addition. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "error",
  "payload": {
    "code": "generic",
    "message": "Card creation failed."
  }
}
CodeDescription
configurationErrorMissing or invalid clientToken
genericCard creation failed

​
Inbound events

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

​
ack

Acknowledge the handshake. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ack"
}