Add Card

Details on working with the Add Card frame used in the Pay with card flow.

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

Property	Type	Required	Description
clientToken	string	✅	The client token returned from the connect flow.
channelId	string	✅	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.
theme	string		Pass dark or light to force a specific appearance. If you omit this, the frame uses the user’s system appearance.

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.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "handshake"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type HandshakeEvent = Message<{
  kind: "handshake";
}>;

ready

The frame finished loading and the card input UI is fully rendered.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ready"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type ReadyEvent = Message<{
  kind: "ready";
}>;

complete

The card was added successfully. Use card.id to get a quote without re-fetching payment methods.

Example

{
  "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 }
    }
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type CardResponse = {
  id: string;
  type: "card";
  cardType: "credit" | "debit" | "unknown";
  brand: "visa" | "mastercard" | "maestro" | "american_express" | "other";
  last4: string;
  expirationMonth: string;
  expirationYear: string;
  availability: { active: boolean };
};

type AddCardCompleteEvent = Message<{
  kind: "complete";
  payload: {
    card: CardResponse;
  };
}>;

error

An error occurred during card addition.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "error",
  "payload": {
    "code": "generic",
    "message": "Card creation failed."
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type AddCardErrorEvent = Message<{
  kind: "error";
  payload: {
    code: "configurationError" | "generic";
    /** A developer-facing error message. Not intended to be rendered in UI. */
    message: string;
  };
}>;

Code	Description
configurationError	Missing or invalid clientToken
generic	Card creation failed

Inbound events

parent->frame

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

ack

Acknowledge the handshake.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ack"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type AckEvent = Message<{
  kind: "ack";
}>;