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.
Fetching Encryption Keys
To encrypt sensitive card information, you first need to retrieve your unique encryption keys. Make a GET request to:Environment Mode. Available Values:
live
, test
mode
.
Encryption Process
When handling sensitive card data, follow these steps:- Fetch the encryption key for your environment (test/live)
- Format the card data as a JSON string
- Generate a random initialization vector (IV)
- Encrypt the data using AES-256-GCM with your encryption key and IV
- Concatenate the hex-encoded IV, ciphertext, and authentication tag
- 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
Security Best Practices
Key Management
Key Management
- 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
Data Handling
Data Handling
- 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
Client-side Security
Client-side Security
- 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
Invalid Encryption Format
Invalid Encryption Format
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
Authentication Failed
Authentication Failed
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
Common Implementation Issues
Common Implementation Issues
- 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