Skip to main content
The Maash checkout widget supports full theme customization. Pass a theme object when creating a checkout session and the returned checkout URL will include the theme parameters automatically.

​
Interactive playground

Use the playground below to experiment with different theme configurations. Copy the generated theme object to include in your create-checkout-session API call.

​
How theming works

Include a theme object in the request body when calling POST /checkout/sessions. The returned checkout_url and checkout_url_with_token will have the theme parameters appended as URL query parameters so the widget renders with your custom look on first load. 
{
  "merchant_id": "mer_01ABC",
  "transaction_id": "txn_123456789",
  "amount_usd": 100,
  "theme": {
    "primaryColor": "#4ade80",
    "backgroundColor": "#f5f5f5",
    "cardColor": "#ffffff"
  }
}
The response URLs are pre-configured with the theme: 
https://pay.maash.io/checkout/cs_01ARZ...?token=eyJ...&primaryColor=%234ade80&backgroundColor=%23f5f5f5&cardColor=%23ffffff
Only the keys you include in the theme object are applied; all other properties use their defaults.

​
Parameter reference

​
Color parameters

Colors accept hex (#RRGGBB, RRGGBB, #RGB) or rgb(r, g, b) format. Background colors automatically derive an accessible foreground color unless you provide an explicit override.
ParameterDescriptionAuto-derives foreground
primaryColorButtons, links, primary accentsYes (primaryButtonTextColor)
primaryButtonTextColorOverride: text on primary buttonsN/A (explicit override)
backgroundColorPage backgroundYes (foregroundColor)
foregroundColorOverride: main text colorN/A (explicit override)
cardColorCard and popover surfacesYes
secondaryColorSecondary elementsYes
mutedColorMuted backgroundsYes
accentColorAccent highlightsYes
destructiveColorError statesYes
borderColorBorders and input outlinesNo
successColorSuccess indicatorsNo
warningColorWarning indicatorsNo
For most use cases, you only need to set primaryColor, backgroundColor, and cardColor. Foreground text colors are automatically derived using WCAG contrast calculations to ensure readability.

​
Integration example

Node.js
const response = await fetch("https://api.maash.io/checkout/sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "mk_live_1234567890abcdef1234567890abcdef",
    "x-maash-user-type": "checkout",
  },
  body: JSON.stringify({
    merchant_id: "mer_01ABC",
    transaction_id: "txn_123456789",
    amount_usd: 100,
    theme: {
      primaryColor: "#4ade80",
      backgroundColor: "#f5f5f5",
      cardColor: "#ffffff",
    },
  }),
});

const { data } = await response.json();
// data.checkout_url_with_token contains the themed checkout URL
// Embed it in an iframe or redirect the customer

​
Next steps

Iframe integration

Set up the iframe and handle payment events.

Create checkout session

Full API reference for creating sessions with theme support.