Security Best Practices

Recommended security practices for integrating with the Bila platform

Security Best Practices

This guide outlines recommended security practices to help you securely integrate with the Bila platform and protect your users’ sensitive financial information.

API Key Security

Your API keys are the primary credentials for accessing the Bila API. Protecting them is critical:

Never expose your secret API keys in client-side code, public repositories, or to unauthorized individuals.

API Key Management

1. Use Environment Variables

   Store API keys in environment variables, not in your code:

   // Good practice
   const bilaClient = new Bila(process.env.BILA_API_KEY);
   
   // Bad practice - Never do this
   const bilaClient = new Bila('sk_live_abcdefg123456789');
   

2. Separate Test and Live Keys

   Use test keys for development and live keys only in production environments.

3. Implement Key Rotation

   Regularly rotate your API keys, especially after team member changes.

   

   API Key Rotation in Bila Console
4. Use Restricted API Keys

   Create keys with the minimum permissions needed for specific services or applications.

Secure Your Integration

TLS/SSL Requirements

Always use HTTPS for all API requests and webhook endpoints. Bila requires TLS 1.2 or higher.

// Node.js example ensuring minimum TLS version
const https = require('https');
const agent = new https.Agent({
  minVersion: 'TLSv1.2'
});

const options = {
  httpsAgent: agent
};

// Use options in your API client configuration

Webhook Security

Secure your webhook endpoints to ensure you only process legitimate requests from Bila:

1. Verify Webhook Signatures

   Always verify the signature included in webhook requests:

   const crypto = require('crypto');
   
   function verifyWebhookSignature(payload, signature, secret) {
     const hmac = crypto.createHmac('sha256', secret);
     const calculatedSignature = hmac.update(payload).digest('hex');
     return crypto.timingSafeEqual(
       Buffer.from(calculatedSignature, 'hex'),
       Buffer.from(signature, 'hex')
     );
   }
   
   // In your webhook handler
   app.post('/webhook', (req, res) => {
     const signature = req.headers['bila-signature'];
     const isValid = verifyWebhookSignature(
       JSON.stringify(req.body),
       signature,
       process.env.BILA_WEBHOOK_SECRET
     );
     
     if (!isValid) {
       return res.status(401).send('Invalid signature');
     }
     
     // Process the webhook
     // ...
   });
   

2. Use HTTPS for Webhooks

   Only configure webhook endpoints that use HTTPS.

3. Implement Retry Logic

   Handle webhook delivery failures gracefully with proper retry logic.

User Authentication & Authorization

When building applications that integrate with Bila, implement strong user authentication:

Multi-Factor Authentication

Multi-Factor Authentication Flow

• Require MFA for all administrative accounts
• Implement MFA for sensitive operations like large transfers
• Support multiple MFA methods (SMS, authenticator apps, security keys)

Session Management

• Set appropriate session timeouts (15-30 minutes for inactivity)
• Regenerate session IDs after authentication
• Implement secure cookie policies:

// Express.js example
app.use(session({
  secret: process.env.SESSION_SECRET,
  cookie: {
    secure: true,           // Only transmit over HTTPS
    httpOnly: true,         // Prevent JavaScript access
    sameSite: 'strict',     // Prevent CSRF
    maxAge: 1800000         // 30 minutes
  },
  resave: false,
  saveUninitialized: false
}));

Data Protection

Sensitive Data Handling

• Never store full card numbers or CVV codes
• Use Bila’s tokenization for payment methods
• Implement data minimization principles

PCI DSS Compliance

If you handle card data directly:

1. Use Bila.js to tokenize card information client-side
2. Maintain PCI DSS compliance for your systems
3. Consider using Bila Checkout to avoid handling card data entirely

Bila.js Tokenization Flow

Fraud Prevention

Implement these measures to reduce fraud risk:

Address Verification

Enable AVS checks for card payments to verify billing addresses

3D Secure

Use 3D Secure for strong customer authentication

Velocity Checks

Monitor and limit the frequency of transactions from the same source

IP Geolocation

Flag transactions from high-risk locations or with IP/location mismatches

Error Handling & Logging

Secure Error Handling

• Never expose sensitive information in error messages
• Use generic error messages for users
• Log detailed errors server-side for debugging

Secure Logging

• Redact sensitive information in logs (API keys, PII, financial data)
• Implement proper log rotation and retention policies
• Use structured logging for better analysis

// Example of redacting sensitive information in logs
const redactedPayload = {
  ...payload,
  card: payload.card ? {
    ...payload.card,
    number: '****' + payload.card.number.slice(-4),
    cvc: '***'
  } : undefined
};

logger.info('Processing payment', { data: redactedPayload });

Regular Security Audits

Maintain a strong security posture with regular reviews:

• Conduct periodic security assessments of your integration
• Keep all dependencies and libraries up to date
• Subscribe to Bila’s security notifications
• Review access logs regularly for suspicious activity

Incident Response

Prepare for security incidents:

1. Develop an incident response plan
2. Know how to rotate compromised API keys quickly
3. Have Bila support contact information readily available
4. Document procedures for communicating with affected users

Related Documentation

Security Overview

Learn about Bila’s security infrastructure and practices

Data Protection

How we protect your data and maintain privacy

Encryption

Details about our encryption technologies and implementations

API Authentication

How to securely authenticate with the Bila API