Security Best Practices

Guidelines for securing your EcobankPay integration

Overview

Security is a critical aspect of any payment integration. This guide covers key security best practices for integrating with EcobankPay, focusing on:

• API authentication and validation
• Secure hash implementation
• Safe credential management
• Transaction verification
• Secure communication

API Authentication

EcobankPay uses a combination of API keys and secure hashing to authenticate requests:

Merchant Key Management

• Your Merchant Key uniquely identifies your account with EcobankPay
• Never share your Merchant Key in public client-side code or repositories
• Store your Merchant Key in secure environment variables or a configuration management system
• Rotate your keys immediately if they are compromised

Secure Hash Implementation (HMAC)

The secure_hash parameter is critical for ensuring the integrity of your API requests:

// Sample Node.js HMAC implementation
const crypto = require('crypto');

function generateSecureHash(params, merchantSecret) {
  // 1. Remove secure_hash if it exists in the params
  const { secure_hash, ...restParams } = params;

  // 2. Sort parameters alphabetically
  const sortedParams = Object.keys(restParams).sort().reduce(
    (obj, key) => {
      obj[key] = restParams[key];
      return obj;
    },
    {}
  );

  // 3. Create parameter string
  const paramString = Object.entries(sortedParams)
    .map(([key, value]) => `${key}=${value}`)
    .join('&');

  // 4. Create HMAC SHA-256 hash
  const hmac = crypto.createHmac('sha256', merchantSecret);
  hmac.update(paramString);

  // 5. Return hex digest
  return hmac.digest('hex');
}

Secure Storage of Credentials

Follow these practices for securely storing your EcobankPay credentials:

• Never hardcode Merchant Keys or Secrets in your application code
• Use environment variables, encrypted configuration files, or a secure vault service
• Implement proper access controls to limit who can access these credentials
• Avoid storing credentials in version control systems
• Consider using a secrets management service like AWS Secrets Manager, HashiCorp Vault, or Azure Key Vault

# .env file (not committed to version control)
ECOBANKPAY_MERCHANT_KEY=abcdef1234-f5d6-4931-8544-58dc97a5
ECOBANKPAY_MERCHANT_SECRET=your-merchant-secret

# In your application
const merchantKey = process.env.ECOBANKPAY_MERCHANT_KEY;
const merchantSecret = process.env.ECOBANKPAY_MERCHANT_SECRET;

Transaction Verification

Always verify transaction statuses to prevent fraud and ensure payment completion:

• Double-check payment status: Always verify payment status through the status check endpoint before fulfilling orders
• Don't rely solely on IPN: Instant Payment Notifications (IPNs) should be treated as prompts to check status, not as confirmation
• Validate IPN requests: Verify that IPN notifications are genuine by checking their origin and content
• Implement idempotency: Ensure your system can handle repeated notifications for the same transaction without duplicate processing

Secure Communication

Ensure all communication with EcobankPay's API is secured:

• Always use HTTPS: Never make API calls over unencrypted HTTP
• Validate SSL certificates: Ensure your client verifies SSL certificates to prevent man-in-the-middle attacks
• Set reasonable timeouts: Configure appropriate connection and request timeouts
• Implement retry logic: Use exponential backoff for retries in case of network failures

// Node.js example with Axios
const axios = require('axios');

const apiClient = axios.create({
  baseURL: 'https://pgw.paywithonline.com/v1',
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json'
  },
  // Enforce certificate validation
  httpsAgent: new https.Agent({
    rejectUnauthorized: true
  })
});

Additional Security Measures

Request Validation

• Validate all inputs before sending them to EcobankPay
• Implement proper data sanitization to prevent injection attacks
• Verify that invoice IDs are unique to prevent duplicate charges
• Validate amount ranges to prevent unusually small or large transactions

Logging and Monitoring

• Implement comprehensive logging for all payment operations
• Monitor for unusual transaction patterns that might indicate fraud
• Log API request and response metadata, but never log sensitive data like card details
• Set up alerts for failed transactions, authentication errors, or unusual activity

PCI Compliance Considerations

• Use EcobankPay's hosted checkout pages to minimize PCI DSS compliance requirements
• Never store, log, or transmit full card details in your systems
• For direct card integrations, ensure your systems comply with PCI DSS requirements
• Regularly review and update your security measures to maintain compliance

Security Checklist

Use this checklist to ensure your EcobankPay integration is secure: