CSP configuration for hosted pages

Overview

To protect your customers and to comply with PCI DSS v4.0.1, Chargebee enforces a strict allowlist Content Security Policy (CSP) on Checkout, Portal, additional payment pages, and all components loaded by Chargebee.js, such as Payment Components and Card Components.

If you use the Google Tag Manager (GTM) integration to deploy scripts or other assets on these pages, you must explicitly allowlist them by uploading a JSON configuration in Chargebee Billing. Otherwise, the assets are blocked.

Configure CSP for hosted pages

Follow these steps to allowlist scripts and other assets on Chargebee hosted pages.

Create a configuration JSON using the examples and JSON schema on this page.
Upload the configuration JSON in Chargebee Billing.

Note

The CSP changes take effect immediately for Checkout, Portal, and other payment pages. However, it can take up to 7 days to apply to the other components loaded by Chargebee.js, such as Payment Components and Card Components.

Warning

The minified version of the configuration JSON must not exceed 5000 characters.

Examples of configuration JSON

Add analytics

CSP header

Content-Security-Policy:
    script-src 'self' https://stats.example.com;
    connect-src 'self' https://api.stats.example.com;
    img-src 'self' https://tracker.stats.example.com;

JSON configuration

{
  "policies": [
    {
      "name": "Basic Analytics",
      "type": "analytics",
      "script-src": {
        "hosts": [
          { "host": "https://stats.example.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      },
      "connect-src": {
        "hosts": [
          { "host": "https://api.stats.example.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      },
      "img-src": {
        "hosts": [
          { "host": "https://tracker.stats.example.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      }
    }
  ]
}

Add analytics and your own JavaScript with hashes

CSP header

Content-Security-Policy:
    script-src 'self' 
               'sha256-k9v+1rD48p+PyMPVGFijWfgSnkelbj/APH3uJacPuoB0=' 
               'sha256-0QF6XTN2zxURUBa+L8+AMfQzCALzVVwaW9xEOsMf/X0=' 
               https://analytics.example.com;
    connect-src 'self' https://api.example.com;
    img-src 'self' data: https://tracker.example.com;

JSON configuration

{
  "policies": [
    {
      "name": "Analytics + Trackers + JavaScript with Hash Validation",
      "type": "custom",
      "script-src": {
        "hosts": [
          { "host": "https://analytics.example.com" }
        ],
        "hashes": [
          "k9v+1rD48p+PyMPVGFijWfgSnkelbj/APH3uJacPuoB0=",
          "0QF6XTN2zxURUBa+L8+AMfQzCALzVVwaW9xEOsMf/X0="
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      },
      "connect-src": {
        "hosts": [
          { "host": "https://api.example.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      },
      "img-src": {
        "hosts": [
          { "host": "https://tracker.example.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" },
          { "type": "SCHEME", "value": "DATA" }
        ]
      }
    }
  ]
}

Use wildcards

CSP header

Content-Security-Policy:
    script-src 'self' https://*.tracking-example.com;
    img-src 'self' data: https://cdn.image-host.com;
    connect-src 'self' https://*.api-service.com;

JSON configuration

{
  "policies": [
    {
      "name": "Tracking and Services",
      "type": "tracking",
      "script-src": {
        "hosts": [
          { "scheme": "https", "host": "*.tracking-example.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      },
      "img-src": {
        "hosts": [
          { "host": "https://cdn.image-host.com" }
        ],
        "expressions": [
          { "type": "SCHEME", "value": "DATA" },
          { "type": "KEYWORD", "value": "SELF" }
        ]
      },
      "connect-src": {
        "hosts": [
          { "scheme": "https", "host": "*.api-service.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      }
    }
  ]
}

JSON schema for CSP configuration

JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CSP Configuration Schema for Chargebee Hosted Capabilities",
  "description": "This schema defines the structure of configuration files that let merchants add Content Security Policy (CSP) directives to Chargebee-hosted capabilities.",
  "type": "object",
  "properties": {
    "policies": {
      "type": "array",
      "description": "An array of CSP configurations. Each configuration specifies a set of CSP directives.",
      "minItems": 1,
      "items": { "$ref": "#/$defs/policy" }
    }
  },
  "required": ["policies"],
  "$defs": {
    "policy": {
      "type": "object",
      "description": "Specifies a set of CSP directives. Chargebee adds a single CSP header to hosted pages. If the same directive appears in multiple policies, Chargebee combines their values.",
      "properties": {
        "name": {
          "type": "string",
          "description": "A unique name of the policy. Use this field to describe the policy's purpose or related service."
        },
        "type": {
          "type": "string",
          "description": "The category of the policy. Use this field to group policies into categories."
        },
        "script-src": { "$ref": "#/$defs/directive" },
        "connect-src": { "$ref": "#/$defs/directive" },
        "frame-src": { "$ref": "#/$defs/directive" },
        "style-src": { "$ref": "#/$defs/directive" },
        "font-src": { "$ref": "#/$defs/directive" },
        "img-src": { "$ref": "#/$defs/directive" },
        "worker-src": { "$ref": "#/$defs/directive" },
        "child-src": { "$ref": "#/$defs/directive" },
        "script-src-elem": { "$ref": "#/$defs/directive" },
        "script-src-attr": { "$ref": "#/$defs/directive" },
        "style-src-elem": { "$ref": "#/$defs/directive" },
        "style-src-attr": { "$ref": "#/$defs/directive" },
        "media-src": { "$ref": "#/$defs/directive" }
      }
    },
    "directive": {
      "type": "object",
      "description": "The value of the CSP directive, specifying the allowed hosts, expressions, and hashes.",
      "properties": {
        "hosts": {
          "type": "array",
          "description": "A list of allowed host sources.",
          "items": { "$ref": "#/$defs/host" }
        },
        "expressions": {
          "type": "array",
          "description": "Additional source expressions that define directive behaviors.",
          "items": { "$ref": "#/$defs/expression" }
        },
        "hashes": {
          "type": "array",
          "description": "A list of Base64-encoded SHA-256 hashes used to allow specific scripts or assets. Chargebee automatically prefixes the hash with 'sha256-' when adding it to the directive.",
          "items": { "$ref": "#/$defs/hash" }
        }
      }
    },
    "host": {
      "type": "object",
      "description": "Defines a host source that the directive allows.",
      "properties": {
        "host": {
          "type": "string",
          "description": "A valid host source for the directive."
        },
        "scheme": {
          "type": "string",
          "description": "The protocol scheme for the 'host' (e.g., 'https', 'http', 'wss')."
        }
      },
      "required": ["host"]
    },
    "expression": {
      "type": "object",
      "description": "Defines a source expression for the directive.",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["SCHEME", "KEYWORD"],
          "description": "The type of source expression.\n- Use 'SCHEME' to indicate a scheme source.\n- Use 'KEYWORD' to indicate forms of source expressions that are not schemes or host sources."
        },
        "value": {
          "type": "string",
          "description": "The value of the source expression. Allowed values depend on the 'type':\n- If 'type' is 'SCHEME', valid values: 'HTTP', 'HTTPS', 'WS', 'WSS', 'DATA', 'BLOB'.\n- If 'type' is 'KEYWORD', valid values: 'SELF', 'UNSAFE_INLINE', 'UNSAFE_EVAL', 'STRICT_DYNAMIC'."
        }
      },
      "required": ["type", "value"]
    },
    "hash": {
      "type": "string",
      "description": "A Base64-encoded SHA-256 hash for an allowed script or other asset. Chargebee automatically prefixes the hash with 'sha256-' when adding it to the directive."
    }
  }
}

Schema description

This section describes each property in the JSON schema.

Root level

Name	Type	Description
`policies`	Array of objects, required	An array of CSP configurations. Each configuration specifies a set of supported CSP fetch directives.

`$defs/policy`

Type: Object

Specifies a set of supported CSP fetch directives. Chargebee adds a single CSP header to hosted pages. If the same directive appears in multiple policies, Chargebee combines their values.

Properties

Name	Type	Description
`name`	String	A unique name of the policy. Use this field to describe the policy's purpose or related service.
`type`	String	The category of the policy. Use this field to group policies into categories.
`connect-src`	Object	The value of the `connect-src` CSP directive.
`script-src`	Object	The value of the `script-src` CSP directive.
`script-src-elem`	Object	The value of the `script-src-elem` CSP directive.
`script-src-attr`	Object	The value of the `script-src-attr` CSP directive.
`child-src`	Object	The value of the `child-src` CSP directive.
`frame-src`	Object	The value of the `frame-src` CSP directive.
`style-src`	Object	The value of the `style-src` CSP directive.
`style-src-elem`	Object	The value of the `style-src-elem` CSP directive.
`style-src-attr`	Object	The value of the `style-src-attr` CSP directive.
`font-src`	Object	The value of the `font-src` CSP directive.
`img-src`	Object	The value of the `img-src` CSP directive.
`worker-src`	Object	The value of the `worker-src` CSP directive.
`media-src`	Object	The value of the `media-src` CSP directive.

`$defs/directive`

Type: Object

The value of the CSP directive, specifying the allowed hosts, expressions, and hashes.

Name	Type	Description
`hosts`	Array of objects	A list of allowed host sources.
`expressions`	Array of objects	Additional source expressions that define directive behaviors.
`hashes`	Array of strings	A list of Base64-encoded SHA-256 hashes used to allow specific scripts or assets. Chargebee automatically prefixes the hash with `sha256-` when adding it to the directive.

`$defs/host`

Type: Object

Defines a host source that the directive allows.

Name	Type	Description
`host`	String, required	A valid host source for the directive.
`scheme`	String	The protocol scheme for the host, for example `https`, `http`, or `wss`.

`$defs/expression`

Type: Object

Defines a source expression for the directive.

Name	Type	Description
`type`	String, required	The type of source expression. Use `SCHEME` to indicate a scheme source. Use `KEYWORD` to indicate forms of source expressions that are not scheme sources or host sources.
`value`	String, required	The value of the source expression. When `type` is `SCHEME`, the valid values are `HTTP`, `HTTPS`, `WS`, `WSS`, `DATA`, and `BLOB`. When `type` is `KEYWORD`, the valid values are `SELF`, `UNSAFE_INLINE`, `UNSAFE_EVAL`, and `STRICT_DYNAMIC`.

`$defs/hash`

Type: String

A Base64-encoded SHA-256 hash for an allowed script or other asset. Chargebee automatically prefixes the hash with sha256- when adding it to the directive.

Articles & FAQs

Content Security Policy for loading the Checkout page

Content security policy for the Checkout page

CSP configuration for hosted pages

Overview

Configure CSP for hosted pages

Follow these steps to allowlist scripts and other assets on Chargebee hosted pages.

Create a configuration JSON using the examples and JSON schema on this page.
Upload the configuration JSON in Chargebee Billing.

Note

Warning

The minified version of the configuration JSON must not exceed 5000 characters.

Examples of configuration JSON

Add analytics

CSP header

Content-Security-Policy:
    script-src 'self' https://stats.example.com;
    connect-src 'self' https://api.stats.example.com;
    img-src 'self' https://tracker.stats.example.com;

JSON configuration

{
  "policies": [
    {
      "name": "Basic Analytics",
      "type": "analytics",
      "script-src": {
        "hosts": [
          { "host": "https://stats.example.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      },
      "connect-src": {
        "hosts": [
          { "host": "https://api.stats.example.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      },
      "img-src": {
        "hosts": [
          { "host": "https://tracker.stats.example.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      }
    }
  ]
}

Add analytics and your own JavaScript with hashes

CSP header

Content-Security-Policy:
    script-src 'self' 
               'sha256-k9v+1rD48p+PyMPVGFijWfgSnkelbj/APH3uJacPuoB0=' 
               'sha256-0QF6XTN2zxURUBa+L8+AMfQzCALzVVwaW9xEOsMf/X0=' 
               https://analytics.example.com;
    connect-src 'self' https://api.example.com;
    img-src 'self' data: https://tracker.example.com;

JSON configuration

{
  "policies": [
    {
      "name": "Analytics + Trackers + JavaScript with Hash Validation",
      "type": "custom",
      "script-src": {
        "hosts": [
          { "host": "https://analytics.example.com" }
        ],
        "hashes": [
          "k9v+1rD48p+PyMPVGFijWfgSnkelbj/APH3uJacPuoB0=",
          "0QF6XTN2zxURUBa+L8+AMfQzCALzVVwaW9xEOsMf/X0="
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      },
      "connect-src": {
        "hosts": [
          { "host": "https://api.example.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      },
      "img-src": {
        "hosts": [
          { "host": "https://tracker.example.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" },
          { "type": "SCHEME", "value": "DATA" }
        ]
      }
    }
  ]
}

Use wildcards

CSP header

Content-Security-Policy:
    script-src 'self' https://*.tracking-example.com;
    img-src 'self' data: https://cdn.image-host.com;
    connect-src 'self' https://*.api-service.com;

JSON configuration

{
  "policies": [
    {
      "name": "Tracking and Services",
      "type": "tracking",
      "script-src": {
        "hosts": [
          { "scheme": "https", "host": "*.tracking-example.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      },
      "img-src": {
        "hosts": [
          { "host": "https://cdn.image-host.com" }
        ],
        "expressions": [
          { "type": "SCHEME", "value": "DATA" },
          { "type": "KEYWORD", "value": "SELF" }
        ]
      },
      "connect-src": {
        "hosts": [
          { "scheme": "https", "host": "*.api-service.com" }
        ],
        "expressions": [
          { "type": "KEYWORD", "value": "SELF" }
        ]
      }
    }
  ]
}

JSON schema for CSP configuration

JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CSP Configuration Schema for Chargebee Hosted Capabilities",
  "description": "This schema defines the structure of configuration files that let merchants add Content Security Policy (CSP) directives to Chargebee-hosted capabilities.",
  "type": "object",
  "properties": {
    "policies": {
      "type": "array",
      "description": "An array of CSP configurations. Each configuration specifies a set of CSP directives.",
      "minItems": 1,
      "items": { "$ref": "#/$defs/policy" }
    }
  },
  "required": ["policies"],
  "$defs": {
    "policy": {
      "type": "object",
      "description": "Specifies a set of CSP directives. Chargebee adds a single CSP header to hosted pages. If the same directive appears in multiple policies, Chargebee combines their values.",
      "properties": {
        "name": {
          "type": "string",
          "description": "A unique name of the policy. Use this field to describe the policy's purpose or related service."
        },
        "type": {
          "type": "string",
          "description": "The category of the policy. Use this field to group policies into categories."
        },
        "script-src": { "$ref": "#/$defs/directive" },
        "connect-src": { "$ref": "#/$defs/directive" },
        "frame-src": { "$ref": "#/$defs/directive" },
        "style-src": { "$ref": "#/$defs/directive" },
        "font-src": { "$ref": "#/$defs/directive" },
        "img-src": { "$ref": "#/$defs/directive" },
        "worker-src": { "$ref": "#/$defs/directive" },
        "child-src": { "$ref": "#/$defs/directive" },
        "script-src-elem": { "$ref": "#/$defs/directive" },
        "script-src-attr": { "$ref": "#/$defs/directive" },
        "style-src-elem": { "$ref": "#/$defs/directive" },
        "style-src-attr": { "$ref": "#/$defs/directive" },
        "media-src": { "$ref": "#/$defs/directive" }
      }
    },
    "directive": {
      "type": "object",
      "description": "The value of the CSP directive, specifying the allowed hosts, expressions, and hashes.",
      "properties": {
        "hosts": {
          "type": "array",
          "description": "A list of allowed host sources.",
          "items": { "$ref": "#/$defs/host" }
        },
        "expressions": {
          "type": "array",
          "description": "Additional source expressions that define directive behaviors.",
          "items": { "$ref": "#/$defs/expression" }
        },
        "hashes": {
          "type": "array",
          "description": "A list of Base64-encoded SHA-256 hashes used to allow specific scripts or assets. Chargebee automatically prefixes the hash with 'sha256-' when adding it to the directive.",
          "items": { "$ref": "#/$defs/hash" }
        }
      }
    },
    "host": {
      "type": "object",
      "description": "Defines a host source that the directive allows.",
      "properties": {
        "host": {
          "type": "string",
          "description": "A valid host source for the directive."
        },
        "scheme": {
          "type": "string",
          "description": "The protocol scheme for the 'host' (e.g., 'https', 'http', 'wss')."
        }
      },
      "required": ["host"]
    },
    "expression": {
      "type": "object",
      "description": "Defines a source expression for the directive.",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["SCHEME", "KEYWORD"],
          "description": "The type of source expression.\n- Use 'SCHEME' to indicate a scheme source.\n- Use 'KEYWORD' to indicate forms of source expressions that are not schemes or host sources."
        },
        "value": {
          "type": "string",
          "description": "The value of the source expression. Allowed values depend on the 'type':\n- If 'type' is 'SCHEME', valid values: 'HTTP', 'HTTPS', 'WS', 'WSS', 'DATA', 'BLOB'.\n- If 'type' is 'KEYWORD', valid values: 'SELF', 'UNSAFE_INLINE', 'UNSAFE_EVAL', 'STRICT_DYNAMIC'."
        }
      },
      "required": ["type", "value"]
    },
    "hash": {
      "type": "string",
      "description": "A Base64-encoded SHA-256 hash for an allowed script or other asset. Chargebee automatically prefixes the hash with 'sha256-' when adding it to the directive."
    }
  }
}

Schema description

This section describes each property in the JSON schema.

Root level

Name	Type	Description
`policies`	Array of objects, required	An array of CSP configurations. Each configuration specifies a set of supported CSP fetch directives.

`$defs/policy`

Type: Object

Specifies a set of supported CSP fetch directives. Chargebee adds a single CSP header to hosted pages. If the same directive appears in multiple policies, Chargebee combines their values.

Properties

Name	Type	Description
`name`	String	A unique name of the policy. Use this field to describe the policy's purpose or related service.
`type`	String	The category of the policy. Use this field to group policies into categories.
`connect-src`	Object	The value of the `connect-src` CSP directive.
`script-src`	Object	The value of the `script-src` CSP directive.
`script-src-elem`	Object	The value of the `script-src-elem` CSP directive.
`script-src-attr`	Object	The value of the `script-src-attr` CSP directive.
`child-src`	Object	The value of the `child-src` CSP directive.
`frame-src`	Object	The value of the `frame-src` CSP directive.
`style-src`	Object	The value of the `style-src` CSP directive.
`style-src-elem`	Object	The value of the `style-src-elem` CSP directive.
`style-src-attr`	Object	The value of the `style-src-attr` CSP directive.
`font-src`	Object	The value of the `font-src` CSP directive.
`img-src`	Object	The value of the `img-src` CSP directive.
`worker-src`	Object	The value of the `worker-src` CSP directive.
`media-src`	Object	The value of the `media-src` CSP directive.

`$defs/directive`

Type: Object

The value of the CSP directive, specifying the allowed hosts, expressions, and hashes.

Name	Type	Description
`hosts`	Array of objects	A list of allowed host sources.
`expressions`	Array of objects	Additional source expressions that define directive behaviors.
`hashes`	Array of strings	A list of Base64-encoded SHA-256 hashes used to allow specific scripts or assets. Chargebee automatically prefixes the hash with `sha256-` when adding it to the directive.

`$defs/host`

Type: Object

Defines a host source that the directive allows.

Name	Type	Description
`host`	String, required	A valid host source for the directive.
`scheme`	String	The protocol scheme for the host, for example `https`, `http`, or `wss`.

`$defs/expression`

Type: Object

Defines a source expression for the directive.

Name	Type	Description
`type`	String, required	The type of source expression. Use `SCHEME` to indicate a scheme source. Use `KEYWORD` to indicate forms of source expressions that are not scheme sources or host sources.
`value`	String, required	The value of the source expression. When `type` is `SCHEME`, the valid values are `HTTP`, `HTTPS`, `WS`, `WSS`, `DATA`, and `BLOB`. When `type` is `KEYWORD`, the valid values are `SELF`, `UNSAFE_INLINE`, `UNSAFE_EVAL`, and `STRICT_DYNAMIC`.

`$defs/hash`

Type: String

A Base64-encoded SHA-256 hash for an allowed script or other asset. Chargebee automatically prefixes the hash with sha256- when adding it to the directive.

Articles & FAQs

Content Security Policy for loading the Checkout page

Content security policy for the Checkout page

Product Updates

Getting Started

Implementing Chargebee

Agentic AI

Developer Resources

Chargebee Apps

Product Catalog

Subscriptions

Customers

Entitlements

Usage Based Billing

Invoices and Credit Notes

Taxes

Hosted Capabilities

Site Configuration

Multi Business Entity

Mobile Subscriptions

Reports and Analytics

Integrations

Data Privacy & Security

Data Operations

CSP configuration for hosted pages

Overview

Configure CSP for hosted pages

Examples of configuration JSON

Add analytics

Add analytics and your own JavaScript with hashes

Use wildcards

JSON schema for CSP configuration

Schema description

Root level

$defs/policy

$defs/directive

$defs/host

$defs/expression

$defs/hash

Articles & FAQs

Product Updates

Getting Started

Implementing Chargebee

Agentic AI

Developer Resources

Chargebee Apps

Product Catalog

Subscriptions

Customers

Entitlements

Usage Based Billing

Invoices and Credit Notes

Taxes

Hosted Capabilities

Site Configuration

Multi Business Entity

Mobile Subscriptions

Reports and Analytics

Integrations

Data Privacy & Security

Data Operations

CSP configuration for hosted pages

Overview

Configure CSP for hosted pages

Examples of configuration JSON

Add analytics

Add analytics and your own JavaScript with hashes

Use wildcards

JSON schema for CSP configuration

Schema description

Root level

$defs/policy

$defs/directive

$defs/host

$defs/expression

$defs/hash

Articles & FAQs

`$defs/policy`

`$defs/directive`

`$defs/host`

`$defs/expression`

`$defs/hash`

`$defs/policy`

`$defs/directive`

`$defs/host`

`$defs/expression`

`$defs/hash`