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 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. themestringPass 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.
handshakeThe frame requests that you open a message channel.
Example
TypeScript definition
{ "version" : 2 , "meta" : { "channelId" : "ch_1" }, "kind" : "handshake" }
type Message < T > = T & { version : 2 ; meta : { channelId : string }; }; type HandshakeEvent = Message <{ kind : "handshake" ; }>;
readyThe frame finished loading and the card input UI is fully rendered.
Example
TypeScript definition
{ "version" : 2 , "meta" : { "channelId" : "ch_1" }, "kind" : "ready" }
type Message < T > = T & { version : 2 ; meta : { channelId : string }; }; type ReadyEvent = Message <{ kind : "ready" ; }>;
completeThe card was added successfully. Use card.id to get a quote without
re-fetching payment methods.
Example
TypeScript definition
{ "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 ; }; }>;
errorAn error occurred during card addition.
Example
TypeScript definition
{ "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 configurationErrorMissing or invalid clientToken genericCard creation failed
Inbound events parent->frame These events are sent from the parent window to this frame.
ackAcknowledge the handshake .
Example
TypeScript definition
{ "version" : 2 , "meta" : { "channelId" : "ch_1" }, "kind" : "ack" }
type Message < T > = T & { version : 2 ; meta : { channelId : string }; }; type AckEvent = Message <{ kind : "ack" ; }>;
