Integration Security Guide

Follow these best practices to ensure your Felloh integration is secure, compliant, and resilient against common threats.

Validate Your PCI Compliance

PCI DSS compliance is a shared responsibility. Felloh achieves PCI DSS Level 1 compliance through our partnership with Basis Theory, a certified PCI Level 1 Service Provider. All sensitive cardholder data is vaulted and processed through Basis Theory's infrastructure — raw card data never enters Felloh's own systems. However, as a business accepting payments, you also have compliance obligations.

By using Felloh's payment form (via the JavaScript SDK or Payment Links), sensitive card data is collected and vaulted directly by Basis Theory and never passes through your servers or ours. This is the simplest path to compliance — in most cases, you only need to complete a Self-Assessment Questionnaire (SAQ A), the lightest PCI requirement.

If you are unsure about your PCI compliance obligations, consult with a Qualified Security Assessor (QSA) or contact our team for guidance.

What You Can Safely Store

The following non-sensitive data returned by the Felloh API is outside the scope of PCI DSS and can be safely stored in your systems:

  • Card brand (e.g. Visa, Mastercard)
  • Last four digits of the card number
  • Expiry month and year
  • Cardholder name
  • Transaction IDs and statuses

You must never store full card numbers, CVV/CVC codes, or PIN data — and with Felloh's integration approach, you will never receive this data in the first place.

Use Low-Risk Integrations

The recommended way to accept payments with Felloh is to use our pre-built payment form via the JavaScript SDK. This approach ensures that:

  • Card data is entered directly into a Felloh-hosted iframe
  • Sensitive data is transmitted directly to Felloh, bypassing your servers entirely
  • Your PCI compliance scope is minimised

Alternatively, you can use Payment Links to send customers to a Felloh-hosted payment page, which requires no frontend integration at all.

Avoid building custom forms that collect card data directly. Doing so brings your servers into PCI scope and requires meeting over 300 security controls under PCI DSS.

Use TLS and HTTPS

All communication between your servers and the Felloh API must use HTTPS with TLS 1.2 or later. The Felloh API will reject any connection attempt over plain HTTP.

You should also ensure that your own website and any pages that embed the Felloh payment form are served over HTTPS. This protects your customers' data in transit and prevents man-in-the-middle attacks.

Recommendations

  • Obtain TLS certificates from a trusted Certificate Authority such as Let's Encrypt (free) or a commercial provider
  • Enable HSTS (HTTP Strict Transport Security) on your domain to prevent protocol downgrade attacks
  • Test your TLS configuration using Qualys SSL Labs — aim for an A or A+ rating
  • Disable older protocols (TLS 1.0, TLS 1.1, SSL) on your servers

Secure Your API Keys

Your Felloh API keys are the gateway to your account. Treat them with the same care as passwords.

Best Practices

  • Never expose private keys in client-side code — Private keys should only be used on your backend servers. Public keys are safe to include in browser-side code.
  • Use environment variables — Store API keys in environment variables or a secrets manager, not in source code or configuration files checked into version control.
  • Rotate keys periodically — Use the API Keys resource to create new keys and retire old ones on a regular schedule.
  • Use separate keys for test and production — Never use production keys in development or staging environments.
  • Restrict access — Only give API key access to team members who need it, and use role-based permissions in the Felloh dashboard.

Storing Keys Securely

# Set in your server environment, not in code
export FELLOH_PUBLIC_KEY="pk_live_..."
export FELLOH_PRIVATE_KEY="sk_live_..."

Verify Webhook Signatures

When receiving webhooks from Felloh, always verify the HMAC-SHA256 signature in the X-Signature header before processing the payload. This confirms that:

  1. The request genuinely came from Felloh
  2. The payload has not been tampered with in transit

All of our server-side SDKs provide built-in helpers for signature verification:

Additional Webhook Security

  • Respond quickly — Return a 2xx status code promptly to acknowledge receipt. Process the webhook payload asynchronously if your handling logic is complex.
  • Handle duplicates — Webhooks may occasionally be delivered more than once. Use the event ID to deduplicate.
  • Use HTTPS — Ensure your webhook endpoint URL uses HTTPS to protect the payload in transit.

Protect Against Common Web Vulnerabilities

If you are building a web application that integrates with Felloh, follow standard web security practices:

  • Cross-Site Scripting (XSS) — Sanitise any user input before rendering it in HTML. Use a Content Security Policy (CSP) to restrict script execution.
  • Cross-Site Request Forgery (CSRF) — Use anti-CSRF tokens on any forms or actions that modify state.
  • SQL Injection — Use parameterised queries or an ORM when interacting with your database. Never interpolate user input into SQL strings.
  • Dependency Management — Keep your dependencies up to date and monitor for known vulnerabilities using tools like npm audit, pip audit, or composer audit.

Content Security Policy

If you use a Content Security Policy on your site and embed the Felloh payment form, ensure your CSP allows connections to Felloh domains:

Content Security Policy

<meta http-equiv="Content-Security-Policy"
  content="frame-src https://sdk.felloh.com https://*.felloh.com;
           script-src https://sdk.felloh.com;">

Further Reading