Frontend Capabilities

# CSP Configuration for Hosted Pages

# Overview

To protect your customers and to comply with PCI DSS v4.0.1 (opens new window), Chargebee enforces an allowlist/strict Content Security Policy (opens new window) (CSP) on Checkout (opens new window), Portal (opens new window), and additional payment pages (opens new window). If you use Google Tag Manager (GTM) integration (opens new window) to deploy scripts or other assets on these pages, you must explicitly allowlist them by uploading a JSON configuration (opens new window) in Chargebee Billing. Otherwise, the assets will be blocked.

# Configure CSP for Hosted Pages

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

  1. Create a configuration JSON using the examples and JSON schema on this page.
  2. Upload the configuration JSON (opens new window) via Chargebee Billing.

The CSP takes effect immediately for all new hosted page sessions.

Character Limit

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

# Examples of configuration JSON

Some sample configurations are provided below.

# 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;
1
2
3
4
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" }
        ]
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# 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;
1
2
3
4
5
6
7
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" }
        ]
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# 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;
1
2
3
4
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" }
        ]
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# 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.",
  "$comment": "For more information, see the documentation at https://www.chargebee.com/checkout-portal-docs/csp-config.html#schema-description.",
  "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."
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

# Schema description

This section describes each property in the JSON schema.

# Root level

Properties
Name Type Description
policies Array of objects Required An array of CSP configurations. Each configuration specifies a set of supported CSP fetch directives (opens new window).

# $defs/policy

Type: Object

Specifies a set of supported CSP fetch directives. Chargebee adds a single CSP header (opens new window) 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 (opens new window) CSP directive.
script-src Object The value of the script-src (opens new window) CSP directive.
script-src-elem Object The value of the script-src-elem (opens new window) CSP directive.
script-src-attr Object The value of the script-src-attr (opens new window) CSP directive.
child-src Object The value of the child-src (opens new window) CSP directive.
frame-src Object The value of the frame-src (opens new window) CSP directive.
style-src Object The value of the style-src (opens new window) CSP directive.
style-src-elem Object The value of the style-src-elem (opens new window) CSP directive.
style-src-attr Object The value of the style-src-attr (opens new window) CSP directive.
font-src Object The value of the font-src (opens new window) CSP directive.
img-src Object The value of the img-src (opens new window) CSP directive.
worker-src Object The value of the worker-src (opens new window) CSP directive.
media-src Object The value of the media-src (opens new window) CSP directive.

# $defs/directive

Type: Object

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

Properties
Name Type Description
hosts Array of objects A list of allowed host sources (opens new window).
expressions Array of objects Additional source expressions (opens new window) that define directive behaviors.
hashes Array of objects A list of Base64-encoded SHA-256 hashes (opens new window) 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 (opens new window) that the directive allows.

Properties
Name Type Description
host String Required A list of allowed host sources (opens new window).
scheme String The protocol scheme for the 'host' (e.g., https, http, wss).

# $defs/expression

Type: Object

Defines a source expressions (opens new window) for the directive.

Properties
Name Type Description
type String Required The type of source expression. Use SCHEME to indicate a scheme source (opens new window). 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. Allowed values depend on the type:
  • If type is SCHEME, valid values are: HTTP, HTTPS, WS, WSS, DATA, BLOB.
  • If type is KEYWORD, valid values are: SELF, UNSAFE_INLINE, UNSAFE_EVAL, STRICT_DYNAMIC.

# $defs/hash

Type: String

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

← Overview →