Theming

Themes control the visual appearance of the hosted checkout page — colours, fonts, logos, and background images. Apply a theme to a checkout session by setting theme_id when creating a checkout. You can upload custom images (logos, backgrounds) and reference them in your theme configuration.

One theme per account can be set as the default (is_default: true). If no theme_id is supplied when creating a checkout, the default theme is applied automatically.

How It Works

1

Upload any images

If your theme requires a custom logo or background, call POST /v2/image first to upload the image. The response returns an image URL to reference in the theme.

2

Create or update the theme

Call POST /v2/theme with your branding configuration. Reference uploaded image URLs in the appropriate theme fields. To modify an existing theme, use PUT /v2/theme/{themeId}.

3

Preview before publishing

Use POST /v2/theme/preview to generate a preview of how the theme will render on the checkout page, without affecting live sessions.

4

Apply to a checkout

Pass the themeId in the theme_id field when calling POST /v2/checkout. See Checkout Sessions.

API Reference

Upload Image

Upload a branding image (logo, background) to reference in theme configurations.

Upload image

post

/v2/image

Body

imagestringRequired

Image file, 500kb max, supported types: png,jpg.

entity_idstringRequired

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

Responses

200

Successful

application/json

idstringRequired

Image ID

checksumnumberOptional

Image checksum

created_atstring · date-timeRequired

Image uploaded time

entity_idstringRequired

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

413

Request Entity Too Large

application/json

500

Internal Server Error

application/json

post/v2/image

POST /oidc/checkout-service/v2/image HTTP/1.1
Host: emea.gsc.verifone.cloud
Content-Type: application/json
Accept: */*
Content-Length: 35

{
  "image": "text",
  "entity_id": "text"
}

{
  "id": "text",
  "checksum": 1,
  "created_at": "2026-01-01T00:00:00.000Z",
  "entity_id": "text"
}

List Themes

Supports RSQL filtering on name, entity_id, is_default, created_at, and updated_at.

RSQL filter examples:

• name==MyTheme;entity_id==a6b45428-0296-4394-8ddd-0b50b5b20aa9
• is_default==true

Combine expressions with ; (AND) or , (OR).

List Themes

get

/v2/theme

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Query parameters

searchstringOptional

Filter themes using RSQL syntax. Combine expressions with ; (AND) or , (OR).

Filterable fields:

Field	Type	Operators
name	string	== != =in= =out= =regex= =contains=
created_at	date	== != =in= =out= =gt= =ge= =lt= =le=
updated_at	date	== != =in= =out= =gt= =ge= =lt= =le=
entity_id	string	== != =in= =out= =regex=
is_default	boolean	== !=

Examples:

• name==MyTheme;entity_id==a6b45428-0296-4394-8ddd-0b50b5b20aa9
• is_default==true

order_criteriastring · enumOptionalPossible values:

order_bystring · enumOptional

The ordering sequence of the selected customers If not selected then Descending order is the default order.

Possible values:

page_numbernumber · min: 1Optional

A filter query in RSQL format to retrieve customers based on page number. If not selected then a default pageNumber is 1.

page_sizenumberOptional

A filter query in RSQL format to retrieve customers based on page size. If not selected then a default pageSize is 50

populate_customer_detailsbooleanOptional

A query param to allow customer details to be populated for the customer id attached to checkout.

Default: false

Responses

200

Successful

application/json

Theme parameters

namestring · max: 255Required

logostringOptional

Uploaded image Id

entity_idstringOptional

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

base_font_familystring · enumOptional

base fonts available for theme

Possible values:

text_colorstringOptional

6 digit hex code, e.g. ffe0e0

heading_colorstringOptional

6 digit hex code, e.g. ffe0e0

background_colorstringOptional

6 digit hex code, e.g. ffe0e0

panel_background_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

primary_color_disabledstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inverse_disabledstringOptional

6 digit hex code, e.g. ffe0e0

error_colorstringOptional

6 digit hex code, e.g. ffe0e0

error_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

input_border_radiusnumberOptional

input_border_widthnumberOptional

hide_verifone_sealbooleanOptional

Show/Hide verifone seal on the checkout page

idstringOptional

created_atstring · dateOptional

updated_atstring · dateOptional

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

get/v2/theme

GET /oidc/checkout-service/v2/theme HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Accept: */*

[
  {
    "name": "text",
    "logo": "text",
    "entity_id": "text",
    "base_font_family": "Roboto",
    "text_color": "text",
    "heading_color": "text",
    "background_color": "text",
    "panel_background_color": "text",
    "primary_color": "text",
    "primary_color_inverse": "text",
    "primary_color_disabled": "text",
    "primary_color_inverse_disabled": "text",
    "error_color": "text",
    "error_color_inverse": "text",
    "input_border_radius": 1,
    "input_border_width": 1,
    "hide_verifone_seal": true,
    "config": {
      "is_default": false
    },
    "id": "text",
    "created_at": "2026-01-01",
    "updated_at": "2026-01-01"
  }
]

Create Theme

Create Theme

post

/v2/theme

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Body

Theme parameters

namestring · max: 255Required

logostringOptional

Uploaded image Id

entity_idstringOptional

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

base_font_familystring · enumOptional

base fonts available for theme

Possible values:

text_colorstringOptional

6 digit hex code, e.g. ffe0e0

heading_colorstringOptional

6 digit hex code, e.g. ffe0e0

background_colorstringOptional

6 digit hex code, e.g. ffe0e0

panel_background_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

primary_color_disabledstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inverse_disabledstringOptional

6 digit hex code, e.g. ffe0e0

error_colorstringOptional

6 digit hex code, e.g. ffe0e0

error_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

input_border_radiusnumberOptional

input_border_widthnumberOptional

hide_verifone_sealbooleanOptional

Show/Hide verifone seal on the checkout page

Default: false

Responses

200

Successful

application/json

Theme parameters

namestring · max: 255Required

logostringOptional

Uploaded image Id

entity_idstringOptional

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

base_font_familystring · enumOptional

base fonts available for theme

Possible values:

text_colorstringOptional

6 digit hex code, e.g. ffe0e0

heading_colorstringOptional

6 digit hex code, e.g. ffe0e0

background_colorstringOptional

6 digit hex code, e.g. ffe0e0

panel_background_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

primary_color_disabledstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inverse_disabledstringOptional

6 digit hex code, e.g. ffe0e0

error_colorstringOptional

6 digit hex code, e.g. ffe0e0

error_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

input_border_radiusnumberOptional

input_border_widthnumberOptional

hide_verifone_sealbooleanOptional

Show/Hide verifone seal on the checkout page

idstringOptional

created_atstring · dateOptional

updated_atstring · dateOptional

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

post/v2/theme

POST /oidc/checkout-service/v2/theme HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 457

{
  "name": "text",
  "logo": "text",
  "entity_id": "text",
  "base_font_family": "Roboto",
  "text_color": "text",
  "heading_color": "text",
  "background_color": "text",
  "panel_background_color": "text",
  "primary_color": "text",
  "primary_color_inverse": "text",
  "primary_color_disabled": "text",
  "primary_color_inverse_disabled": "text",
  "error_color": "text",
  "error_color_inverse": "text",
  "input_border_radius": 1,
  "input_border_width": 1,
  "hide_verifone_seal": false,
  "config": {
    "is_default": false
  }
}

{
  "name": "text",
  "logo": "text",
  "entity_id": "text",
  "base_font_family": "Roboto",
  "text_color": "text",
  "heading_color": "text",
  "background_color": "text",
  "panel_background_color": "text",
  "primary_color": "text",
  "primary_color_inverse": "text",
  "primary_color_disabled": "text",
  "primary_color_inverse_disabled": "text",
  "error_color": "text",
  "error_color_inverse": "text",
  "input_border_radius": 1,
  "input_border_width": 1,
  "hide_verifone_seal": true,
  "config": {
    "is_default": false
  },
  "id": "text",
  "created_at": "2026-01-01",
  "updated_at": "2026-01-01",
  "details": {
    "warnings": [
      {}
    ]
  }
}

Preview Theme

Preview Theme

post

/v2/theme/preview

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Body

Preview theme parameters

namestring · max: 255Optional

theme_idstringOptional

Parameter that was created within the create theme API call that applies the customizations upon the checkout interface. Read Theming for details.

logostringOptional

Uploaded image id

base_font_familystring · enumOptional

base fonts available for theme

Possible values:

text_colorstringOptional

6 digit hex code, e.g. ffe0e0

heading_colorstringOptional

6 digit hex code, e.g. ffe0e0

background_colorstringOptional

6 digit hex code, e.g. ffe0e0

panel_background_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

primary_color_disabledstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inverse_disabledstringOptional

6 digit hex code, e.g. ffe0e0

error_colorstringOptional

6 digit hex code, e.g. ffe0e0

error_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

input_border_radiusnumberOptional

input_border_widthnumberOptional

hide_verifone_sealbooleanOptional

Show/Hide verifone seal on the checkout page

Default: false

Responses

200

Successful

application/json

imagestringRequired

Previewed image converted to base64 (image type is .png)

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

post/v2/theme/preview

POST /oidc/checkout-service/v2/theme/preview HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 481

{
  "name": "text",
  "theme_id": "text",
  "logo": "text",
  "base_font_family": "Roboto",
  "text_color": "text",
  "heading_color": "text",
  "background_color": "text",
  "panel_background_color": "text",
  "primary_color": "text",
  "primary_color_inverse": "text",
  "primary_color_disabled": "text",
  "primary_color_inverse_disabled": "text",
  "error_color": "text",
  "error_color_inverse": "text",
  "input_border_radius": 1,
  "input_border_width": 1,
  "hide_verifone_seal": false,
  "response_image_size": {
    "width": "text",
    "height": "text"
  }
}

{
  "image": "text",
  "response_image_size": {
    "width": "text",
    "height": "text"
  }
}

Get a Theme by ID

Get a theme by id

get

/v2/theme/{themeId}

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Path parameters

themeIdstringRequired

Parameter that was created within the create theme API call that applies the customizations upon the checkout interface. Read Theming for details.

Responses

200

Successful

application/json

Theme parameters

namestring · max: 255Required

logostringOptional

Uploaded image Id

entity_idstringOptional

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

base_font_familystring · enumOptional

base fonts available for theme

Possible values:

text_colorstringOptional

6 digit hex code, e.g. ffe0e0

heading_colorstringOptional

6 digit hex code, e.g. ffe0e0

background_colorstringOptional

6 digit hex code, e.g. ffe0e0

panel_background_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

primary_color_disabledstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inverse_disabledstringOptional

6 digit hex code, e.g. ffe0e0

error_colorstringOptional

6 digit hex code, e.g. ffe0e0

error_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

input_border_radiusnumberOptional

input_border_widthnumberOptional

hide_verifone_sealbooleanOptional

Show/Hide verifone seal on the checkout page

idstringOptional

created_atstring · dateOptional

updated_atstring · dateOptional

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get/v2/theme/{themeId}

GET /oidc/checkout-service/v2/theme/{themeId} HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Accept: */*

{
  "name": "text",
  "logo": "text",
  "entity_id": "text",
  "base_font_family": "Roboto",
  "text_color": "text",
  "heading_color": "text",
  "background_color": "text",
  "panel_background_color": "text",
  "primary_color": "text",
  "primary_color_inverse": "text",
  "primary_color_disabled": "text",
  "primary_color_inverse_disabled": "text",
  "error_color": "text",
  "error_color_inverse": "text",
  "input_border_radius": 1,
  "input_border_width": 1,
  "hide_verifone_seal": true,
  "config": {
    "is_default": false
  },
  "id": "text",
  "created_at": "2026-01-01",
  "updated_at": "2026-01-01"
}

Update Theme

Update Theme

put

/v2/theme/{themeId}

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Path parameters

themeIdstringRequired

Parameter that was created within the create theme API call that applies the customizations upon the checkout interface. Read Theming for details.

Body

Theme parameters

namestring · max: 255Required

logostringOptional

Uploaded image Id

entity_idstringOptional

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

base_font_familystring · enumOptional

base fonts available for theme

Possible values:

text_colorstringOptional

6 digit hex code, e.g. ffe0e0

heading_colorstringOptional

6 digit hex code, e.g. ffe0e0

background_colorstringOptional

6 digit hex code, e.g. ffe0e0

panel_background_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

primary_color_disabledstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inverse_disabledstringOptional

6 digit hex code, e.g. ffe0e0

error_colorstringOptional

6 digit hex code, e.g. ffe0e0

error_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

input_border_radiusnumberOptional

input_border_widthnumberOptional

hide_verifone_sealbooleanOptional

Show/Hide verifone seal on the checkout page

Responses

200

Successful

application/json

Theme parameters

namestring · max: 255Required

logostringOptional

Uploaded image Id

entity_idstringOptional

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

base_font_familystring · enumOptional

base fonts available for theme

Possible values:

text_colorstringOptional

6 digit hex code, e.g. ffe0e0

heading_colorstringOptional

6 digit hex code, e.g. ffe0e0

background_colorstringOptional

6 digit hex code, e.g. ffe0e0

panel_background_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_colorstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

primary_color_disabledstringOptional

6 digit hex code, e.g. ffe0e0

primary_color_inverse_disabledstringOptional

6 digit hex code, e.g. ffe0e0

error_colorstringOptional

6 digit hex code, e.g. ffe0e0

error_color_inversestringOptional

6 digit hex code, e.g. ffe0e0

input_border_radiusnumberOptional

input_border_widthnumberOptional

hide_verifone_sealbooleanOptional

Show/Hide verifone seal on the checkout page

idstringOptional

created_atstring · dateOptional

updated_atstring · dateOptional

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

put/v2/theme/{themeId}

PUT /oidc/checkout-service/v2/theme/{themeId} HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 456

{
  "name": "text",
  "logo": "text",
  "entity_id": "text",
  "base_font_family": "Roboto",
  "text_color": "text",
  "heading_color": "text",
  "background_color": "text",
  "panel_background_color": "text",
  "primary_color": "text",
  "primary_color_inverse": "text",
  "primary_color_disabled": "text",
  "primary_color_inverse_disabled": "text",
  "error_color": "text",
  "error_color_inverse": "text",
  "input_border_radius": 1,
  "input_border_width": 1,
  "hide_verifone_seal": true,
  "config": {
    "is_default": false
  }
}

{
  "name": "text",
  "logo": "text",
  "entity_id": "text",
  "base_font_family": "Roboto",
  "text_color": "text",
  "heading_color": "text",
  "background_color": "text",
  "panel_background_color": "text",
  "primary_color": "text",
  "primary_color_inverse": "text",
  "primary_color_disabled": "text",
  "primary_color_inverse_disabled": "text",
  "error_color": "text",
  "error_color_inverse": "text",
  "input_border_radius": 1,
  "input_border_width": 1,
  "hide_verifone_seal": true,
  "config": {
    "is_default": false
  },
  "id": "text",
  "created_at": "2026-01-01",
  "updated_at": "2026-01-01",
  "details": {
    "warnings": [
      {}
    ]
  }
}

Delete Theme by ID

Deleting a theme is irreversible. Any checkout sessions referencing the deleted theme will fall back to the account default theme.

Delete a theme by id

delete

/v2/theme/{themeId}

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Path parameters

themeIdstringRequired

Parameter that was created within the create theme API call that applies the customizations upon the checkout interface. Read Theming for details.

Responses

204

Success. Theme was successfully deleted.

No content

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

delete/v2/theme/{themeId}

DELETE /oidc/checkout-service/v2/theme/{themeId} HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Accept: */*

No content

Count Themes

Count Themes

get

/v2/theme/count

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Query parameters

searchstringRequired

Filter themes using RSQL syntax. Combine expressions with ; (AND) or , (OR).

Filterable fields:

Field	Type	Operators
name	string	== != =in= =out= =regex= =contains=
created_at	date	== != =in= =out= =gt= =ge= =lt= =le=
updated_at	date	== != =in= =out= =gt= =ge= =lt= =le=
entity_id	string	== != =in= =out= =regex=
is_default	boolean	== !=

Examples:

• name==MyTheme;entity_id==a6b45428-0296-4394-8ddd-0b50b5b20aa9
• is_default==true

Responses

200

Successful

application/json

countnumberOptional

Count

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

get/v2/theme/count

GET /oidc/checkout-service/v2/theme/count?search=text HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Accept: */*

{
  "count": 1
}