Content Security Policy (CSP) Configuration

Content Security Policy (CSP) is a security feature that helps prevent cross-site scripting (XSS) attacks. When integrating FramePay, you need to configure your CSP to allow the necessary domains.

Overview

FramePay loads payment fields via secure iframes and requires specific CSP directives to function properly. This guide covers:

🔒 Required CSP directives
🌐 Allowed domains
⚙️ Configuration methods
🎯 Best practices

Required CSP Directives

Minimum Configuration

To use FramePay with card payments only, include these directives:

<meta http-equiv="Content-Security-Policy" content="
  default-src 'self';
  script-src 'self' 'unsafe-inline' framepay.payments.ai;
  connect-src 'self' framepay.payments.ai *.payments.ai;
  style-src 'self' 'unsafe-inline' framepay.payments.ai;
  frame-src 'self' framepay.payments.ai;
  img-src 'self' data: framepay.payments.ai;
  font-src 'self';
">

Full Configuration (with Digital Wallets)

If you're using Apple Pay, Google Pay, or PayPal, add their domains:

<meta http-equiv="Content-Security-Policy" content="
  default-src 'self';
  script-src 'self' 'unsafe-inline' 
    framepay.payments.ai 
    *.paypal.com 
    *.google.com 
    *.cdn-apple.com;
  connect-src 'self' 
    framepay.payments.ai 
    *.payments.ai 
    *.paypal.com 
    *.google.com 
    *.apple.com;
  style-src 'self' 'unsafe-inline' 
    framepay.payments.ai 
    fonts.googleapis.com;
  frame-src 'self' 
    framepay.payments.ai 
    *.paypal.com 
    *.google.com;
  img-src 'self' data: 
    framepay.payments.ai 
    *.paypal.com 
    *.google.com;
  font-src 'self' 
    fonts.gstatic.com;
">

Configuration Methods

Method 1: HTML Meta Tag

Add the CSP meta tag in your HTML <head> section:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="Content-Security-Policy" content="
    default-src 'self';
    script-src 'self' 'unsafe-inline' framepay.payments.ai *.paypal.com *.google.com *.cdn-apple.com;
    connect-src 'self' framepay.payments.ai *.payments.ai *.paypal.com *.google.com;
    style-src 'self' 'unsafe-inline' framepay.payments.ai fonts.googleapis.com;
    frame-src 'self' framepay.payments.ai *.paypal.com *.google.com;
    img-src 'self' data: framepay.payments.ai *.paypal.com *.google.com;
    font-src 'self' fonts.gstatic.com;
  ">
  <title>Checkout</title>
</head>
<body>
  <!-- Your content here -->
</body>
</html>

Method 2: HTTP Header (Recommended)

Configure CSP via HTTP headers on your server. This is the recommended approach for production.

Node.js/Express

const express = require('express');
const app = express();

app.use((req, res, next) => {
  res.setHeader(
    'Content-Security-Policy',
    "default-src 'self'; " +
    "script-src 'self' 'unsafe-inline' framepay.payments.ai *.paypal.com *.google.com *.cdn-apple.com; " +
    "connect-src 'self' framepay.payments.ai *.payments.ai *.paypal.com *.google.com; " +
    "style-src 'self' 'unsafe-inline' framepay.payments.ai fonts.googleapis.com; " +
    "frame-src 'self' framepay.payments.ai *.paypal.com *.google.com; " +
    "img-src 'self' data: framepay.payments.ai *.paypal.com *.google.com; " +
    "font-src 'self' fonts.gstatic.com;"
  );
  next();
});

Nginx

location / {
    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' framepay.payments.ai *.paypal.com *.google.com *.cdn-apple.com; connect-src 'self' framepay.payments.ai *.payments.ai *.paypal.com *.google.com; style-src 'self' 'unsafe-inline' framepay.payments.ai fonts.googleapis.com; frame-src 'self' framepay.payments.ai *.paypal.com *.google.com; img-src 'self' data: framepay.payments.ai *.paypal.com *.google.com; font-src 'self' fonts.gstatic.com;";
}

Apache

<IfModule mod_headers.c>
    Header set Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' framepay.payments.ai *.paypal.com *.google.com *.cdn-apple.com; connect-src 'self' framepay.payments.ai *.payments.ai *.paypal.com *.google.com; style-src 'self' 'unsafe-inline' framepay.payments.ai fonts.googleapis.com; frame-src 'self' framepay.payments.ai *.paypal.com *.google.com; img-src 'self' data: framepay.payments.ai *.paypal.com *.google.com; font-src 'self' fonts.gstatic.com;"
</IfModule>

Next.js

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: [
              "default-src 'self'",
              "script-src 'self' 'unsafe-inline' framepay.payments.ai *.paypal.com *.google.com *.cdn-apple.com",
              "connect-src 'self' framepay.payments.ai *.payments.ai *.paypal.com *.google.com",
              "style-src 'self' 'unsafe-inline' framepay.payments.ai fonts.googleapis.com",
              "frame-src 'self' framepay.payments.ai *.paypal.com *.google.com",
              "img-src 'self' data: framepay.payments.ai *.paypal.com *.google.com",
              "font-src 'self' fonts.gstatic.com"
            ].join('; ')
          }
        ]
      }
    ]
  }
}

CSP Directive Breakdown

`default-src 'self'`

Sets the default policy for all content types. 'self' allows content only from your own domain.

`script-src`

Controls which JavaScript sources are allowed:

'self' - Your own domain
'unsafe-inline' - Required for FramePay inline scripts
framepay.payments.ai - FramePay CDN
*.paypal.com - PayPal SDK (if using PayPal)
*.google.com - Google Pay SDK (if using Google Pay)
*.cdn-apple.com - Apple Pay SDK (if using Apple Pay)

⚠️ Security Note: 'unsafe-inline' reduces CSP protection. For production, consider using nonces for better security.

`connect-src`

Controls which domains can be contacted via XHR, WebSocket, or EventSource:

'self' - Your own domain
framepay.payments.ai - FramePay API
*.payments.ai - Payments AI API
*.paypal.com - PayPal API
*.google.com - Google Pay API

`style-src`

Controls stylesheet sources:

'self' - Your own stylesheets
'unsafe-inline' - Required for inline styles
framepay.payments.ai - FramePay CSS
fonts.googleapis.com - Google Fonts (if used)

`frame-src`

Controls which sources can be loaded in iframes (crucial for FramePay):

'self' - Your own domain
framepay.payments.ai - FramePay payment fields
*.paypal.com - PayPal iframe
*.google.com - Google Pay iframe

`img-src`

Controls image sources:

'self' - Your own images
data: - Required for data URIs (card brand icons)
framepay.payments.ai - FramePay images
*.paypal.com - PayPal logos
*.google.com - Google Pay logos

`font-src`

Controls font sources:

'self' - Your own fonts
fonts.gstatic.com - Google Fonts (if used)

Payment Method Specific Configuration

Card Payments Only

<meta http-equiv="Content-Security-Policy" content="
  default-src 'self';
  script-src 'self' 'unsafe-inline' framepay.payments.ai;
  connect-src 'self' framepay.payments.ai *.payments.ai;
  style-src 'self' 'unsafe-inline' framepay.payments.ai;
  frame-src 'self' framepay.payments.ai;
  img-src 'self' data: framepay.payments.ai;
">

Apple Pay

Add these domains for Apple Pay:

script-src: *.cdn-apple.com
connect-src: *.apple.com

Google Pay

Add these domains for Google Pay:

script-src: *.google.com
connect-src: *.google.com
frame-src: *.google.com
img-src: *.google.com

PayPal

Add these domains for PayPal:

script-src: *.paypal.com
connect-src: *.paypal.com
frame-src: *.paypal.com
img-src: *.paypal.com

Using Nonces (Production)

For better security, use nonces instead of 'unsafe-inline':

Backend (Node.js/Express)

const crypto = require('crypto');

app.use((req, res, next) => {
  // Generate nonce for this request
  const nonce = crypto.randomBytes(16).toString('base64');
  res.locals.nonce = nonce;
  
  res.setHeader(
    'Content-Security-Policy',
    `default-src 'self'; ` +
    `script-src 'self' 'nonce-${nonce}' framepay.payments.ai; ` +
    `style-src 'self' 'nonce-${nonce}' framepay.payments.ai;`
  );
  next();
});

Frontend

<!-- Use the nonce in your script tags -->
<script nonce="<%= nonce %>">
  Framepay.initialize({
    publishableKey: 'pk_sandbox_xxx',
    // ... config
  });
</script>

Testing CSP Configuration

Browser Console

Open your browser's developer console (F12) and look for CSP violations:

Refused to load the script 'https://example.com/script.js' because it 
violates the following Content Security Policy directive...

CSP Report Mode

Test your CSP without blocking resources using Content-Security-Policy-Report-Only:

<meta http-equiv="Content-Security-Policy-Report-Only" content="
  default-src 'self';
  script-src 'self' 'unsafe-inline' framepay.payments.ai;
  report-uri /csp-violation-report-endpoint;
">

This will report violations without blocking them, allowing you to test safely.

Online Tools

Use these tools to validate your CSP:

CSP Evaluator - Google's CSP validation tool
CSP Scanner - Comprehensive CSP analysis

Common Issues

Issue: FramePay not loading

Symptom: FramePay fields don't appear

Solution: Ensure script-src includes framepay.payments.ai and frame-src allows framepay.payments.ai

script-src 'self' 'unsafe-inline' framepay.payments.ai;
frame-src 'self' framepay.payments.ai;

Issue: Card brand icons not showing

Symptom: Visa, Mastercard logos don't appear

Solution: Add data: to img-src:

img-src 'self' data: framepay.payments.ai;

Issue: Wallet buttons not working

Symptom: Apple Pay/Google Pay/PayPal buttons don't respond

Solution: Add wallet provider domains to all relevant directives:

script-src 'self' 'unsafe-inline' framepay.payments.ai *.paypal.com *.google.com;
connect-src 'self' framepay.payments.ai *.payments.ai *.paypal.com *.google.com;
frame-src 'self' framepay.payments.ai *.paypal.com *.google.com;

Issue: HTTPS mixed content

Symptom: Console shows mixed content warnings

Solution: Ensure your page is served over HTTPS in production. CSP cannot fix HTTP served over HTTPS.

Best Practices

✅ Do

Use HTTP headers over meta tags when possible
Start with Content-Security-Policy-Report-Only for testing
Be as restrictive as possible while allowing necessary domains
Use nonces or hashes instead of 'unsafe-inline' in production
Document your CSP configuration
Monitor CSP violation reports

❌ Don't

Use 'unsafe-eval' - it's not required for FramePay
Allow * wildcards - they defeat the purpose of CSP
Forget to test on all payment methods you support
Mix HTTP and HTTPS content
Skip CSP validation in staging environments

Environment-Specific Configuration

Development

Content-Security-Policy-Report-Only: ...

Use report-only mode to identify issues without breaking functionality.

Staging

Content-Security-Policy: ...

Enforce CSP but with more permissive settings for testing.

Production

Content-Security-Policy: ... (strict configuration)

Use the strictest possible CSP with nonces and minimal wildcards.

Additional Security Headers

Consider adding these headers alongside CSP:

X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains
Referrer-Policy: strict-origin-when-cross-origin

Resources

Next Steps

📖 Client-Side Integration - Set up FramePay on your frontend
🔄 Payment Flows - Understand payment processing
📚 Complete Example - See it all working together

Overview​

Required CSP Directives​

Minimum Configuration​

Full Configuration (with Digital Wallets)​

Configuration Methods​

Method 1: HTML Meta Tag​

Method 2: HTTP Header (Recommended)​

Node.js/Express​

Nginx​

Apache​

Next.js​

CSP Directive Breakdown​

default-src 'self'​

script-src​

connect-src​

style-src​

frame-src​

img-src​

font-src​

Payment Method Specific Configuration​

Card Payments Only​

Apple Pay​

Google Pay​

PayPal​

Using Nonces (Production)​

Backend (Node.js/Express)​

Frontend​

Testing CSP Configuration​

Browser Console​

CSP Report Mode​

Online Tools​

Common Issues​

Issue: FramePay not loading​

Issue: Card brand icons not showing​

Issue: Wallet buttons not working​

Issue: HTTPS mixed content​

Best Practices​

✅ Do​

❌ Don't​

Environment-Specific Configuration​

Development​

Staging​

Production​

Additional Security Headers​

Resources​

Next Steps​