Skip to navigation
Customization Options

Customizing theme for Headless Payments

Transaction Session API theme customization config options for Headless Apple Pay, Headless Google Pay, and Headless Cards.
View as Markdown

Each Headless Payments flow uses a Transaction Session API to generate a sessionId that initialises the respective payment component via the Transak UI SDK. This guide covers the optional config object available on each Headless Payments flow.

Headless Apple Pay

The Transaction Session API used in Headless Apple Pay accepts an optional config object to customise the look and feel of the Apple Pay button component. Partners can use it to control the colorMode, corner rounding, and height of the embedded button.

config object

FieldDescription
colorModeSwitches the button between a dark or light theme so it matches the rest of your page. Set to DARK or LIGHT.
borderRadiusRounds the corners of the button. Accepts a CSS value in px or rem, for example 8px for softly rounded corners.
heightSets how tall the button renders. Accepts a CSS value in px or rem, for example 48px.

Sample Request

curl --request POST \
  --url https://api-gateway-stg.transak.com/api/v2/transaction-session \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-user-ip: YOUR_USER_IP' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'authorization: YOUR_ACCESS_TOKEN' \
  --data '{
    "quoteId": "YOUR_QUOTE_ID",
    "walletAddress": "YOUR_WALLET_ADDRESS",
    "config": {
      "colorMode": "LIGHT",
      "borderRadius": "8px",
      "height": "48px"
    }
  }'

A successful response returns a sessionId used to mount the Apple Pay component via the Transak UI SDK.

Headless Google Pay

The Transaction Session API used in Headless Google Pay accepts an optional config object to customise the look and feel of the Google Pay component. Partners can use it to control the colorMode, corner rounding, and height of the embedded button.

config object

FieldDescription
colorModeSwitches the button between a dark or light theme so it matches the rest of your page. Set to DARK or LIGHT.
borderRadiusRounds the corners of the button. Accepts a CSS value in px or rem, for example 8px for softly rounded corners.
heightSets how tall the button renders. Accepts a CSS value in px or rem, for example 48px.

Sample Request

curl --request POST \
  --url https://api-gateway-stg.transak.com/api/v2/transaction-session \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-user-ip: YOUR_USER_IP' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'authorization: YOUR_ACCESS_TOKEN' \
  --data '{
    "quoteId": "YOUR_QUOTE_ID",
    "walletAddress": "YOUR_WALLET_ADDRESS",
    "successUrl": "https://yourdomain.com/success",
    "failureUrl": "https://yourdomain.com/failure",
    "config": {
      "colorMode": "DARK",
      "borderRadius": "8px",
      "height": "48px"
    }
  }'

A successful response returns a sessionId and expiresAt used to mount the Google Pay component via the Transak UI SDK.

Headless Cards

The Transaction Session API used in Headless Cards accepts an optional config object to customise the look and feel of the card payment form. Use colorMode to switch between dark and light themes, or colors to override individual theme colors with your own brand palette.

config object

FieldDescription
colorModeSwitches the card form between a dark or light theme so it matches the rest of your page. Set to DARK or LIGHT.
colorsLets you go beyond colorMode and hand-pick individual colors across the card form to match your brand.

colors object

FieldDescription
widgetBackgroundFillColorThe background color behind the card form. Pass a hex value.
brandColorThe color that appears around an input field when a user taps into it. Pass a hex value.
textPrimaryColorThe color of the text users type into the card fields. Pass a hex value.
textSecondaryColorThe color of field labels and placeholder text, like “Card number”. Pass a hex value.
surfaceFillColorThe background color of the input fields themselves. Pass a hex value.
borderColorThe default border color around input fields when they’re not focused. Pass a hex value.
redColorThe color shown for validation errors, used on both the border and the error text. Pass a hex value.

Sample Request

curl --request POST \
  --url https://api-gateway-stg.transak.com/api/v2/transaction-session \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-user-ip: YOUR_USER_IP' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'authorization: YOUR_ACCESS_TOKEN' \
  --data '{
    "quoteId": "YOUR_QUOTE_ID",
    "walletAddress": "YOUR_WALLET_ADDRESS",
    "successUrl": "https://yourdomain.com/success",
    "failureUrl": "https://yourdomain.com/failure",
    "config": {
      "colorMode": "LIGHT",
      "colors": {
        "widgetBackgroundFillColor": "#F4F4F4",
        "brandColor": "#1461DB",
        "textPrimaryColor": "#000000",
        "textSecondaryColor": "#666666",
        "surfaceFillColor": "#F5F5F5",
        "borderColor": "#EBEBEB",
        "redColor": "#F32139"
      }
    }
  }'

A successful response returns a sessionId and expiresAt used to mount the card component via the Transak UI SDK.