Skip to main content

​
Payment Data Encryption

Never send raw card data directly to your backend or our API. All sensitive payment information must be encrypted client-side before transmission.
Protecting customer payment information is critical. Our API uses strong encryption to safeguard sensitive data. This guide explains how to securely handle encryption for card data in your integration.

​
Fetching Encryption Keys

To encrypt sensitive card information, you first need to retrieve your unique encryption keys. Make a GET request to: 
GET /payment-sessions/encryption-keys/:mode
Parameters
​
mode
string
required
Environment Mode. Available Values: live, test
Successful Response (200 OK): 
{
  "data": {
    "encryption_key": "67634cc972d2433b8725c8f6fbfdf792"
  }
}
Error Response (400 Bad Request): Indicates an issue with the request, such as an invalid mode.

​
Encryption Process

When handling sensitive card data, follow these steps:
  1. Fetch the encryption key for your environment (test/live)
  2. Format the card data as a JSON string
  3. Generate a random initialization vector (IV)
  4. Encrypt the data using AES-256-GCM with your encryption key and IV
  5. Concatenate the hex-encoded IV, ciphertext, and authentication tag
  6. Send the encrypted data to our API
Never send raw card data directly to your backend or our API. Always encrypt it first on the client-side.

​
Code Examples

  • PHP
  • JavaScript
  • Python
  • Ruby
function card_encrypt($payload, $key) {
    $iv = openssl_random_pseudo_bytes(16);
    $cipher_text = openssl_encrypt(
        $payload, 
        "aes-256-gcm", 
        $key, 
        OPENSSL_RAW_DATA, 
        $iv, 
        $tag
    );
    return implode(':', [
        bin2hex($iv),
        bin2hex($cipher_text),
        bin2hex($tag)
    ]);
}

// Example usage
$card_data = json_encode([
    'card_number' => '4111111111111111',
    'expiry_month' => '12',
    'expiry_year' => '2025',
    'cvv' => '123'
]);
$encrypted = card_encrypt($card_data, $encryption_key);

​
Security Best Practices

  • Store encryption keys securely in environment variables or a key management service
  • Never commit encryption keys to source control
  • Rotate encryption keys periodically (we’ll notify you before key expiration)
  • Use different keys for test and production environments
  • Encrypt sensitive data as soon as it’s collected
  • Clear sensitive data from memory after use
  • Never log or store raw card data
  • Use HTTPS for all API communications
  • Implement Content Security Policy (CSP) headers
  • Use Subresource Integrity for external scripts
  • Minimize the time sensitive data remains in memory
  • Clear form fields after encryption

​
Troubleshooting Guide

If you receive an “Invalid encryption format” error:
  • Verify the encryption key is correct and valid
  • Ensure IV, ciphertext, and tag are properly concatenated with colons
  • Check that all components are properly hex-encoded
If you receive an “Authentication failed” error:
  • Verify you’re using the correct encryption key for your environment
  • Check that the authentication tag is being properly generated and included
  • Ensure the payload hasn’t been modified after encryption
  • Random IV Generation: Ensure a new random IV is generated for each encryption
  • Memory Management: Clear sensitive data from variables after use
  • Encoding Issues: Verify proper encoding/decoding of binary data to hex
  • Library Version Compatibility: Check cryptographic library versions match requirements