Integration Security Guide

Ensuring the security of your integration with Yellow Card's API is crucial to protect sensitive data and maintain system integrity. The following best practices are recommended:

1. Secure API Authentication

Use HMAC Authentication

Description: Yellow Card’s API requires HMAC (Hash-based Message Authentication Code) for authentication.

Best Practices:

• Secure Storage of API Keys and Secrets: Store secrets securely using methods such as environment variables or dedicated secret management tools.
• Regular Rotation of API Keys and Secrets: Periodically rotate secrets to minimize the impact of potential exposure.
• Avoid Hardcoding API Keys and Secrets: Do not hardcode secrets in your source code or share them via unsecured channels.

2. Implement API Key Management & Permissions

Description: Yellow Card allows merchants to configure API key permissions to restrict access based on specific operational needs.

Best Practices:

• Principle of Least Privilege: Assign API keys only the necessary permissions. For example, use read-only access for monitoring and full access for critical transactions.
• Separate API Keys for Different Functions: Maintain separate API keys for different functions, such as processing transactions and querying balances.
• Environment-Specific API Keys: Avoid sharing API keys across different environments (e.g., production and staging) to reduce the risk of exposure.

3. Secure Your Server Environment

Implement IP Whitelisting

Description: Yellow Card requires merchants to provide a static IP address for whitelisting in the production environment.

Best Practices:

• Use Static IP Addresses: Ensure your servers use static IP addresses to facilitate consistent whitelisting.

4. Secure Webhooks

Validate Webhook Requests

Description: Webhooks allow Yellow Card to send real-time notifications to your server. Ensuring these requests are secure is vital.

Best Practices:

• Verify HMAC Signatures: Validate the HMAC signature included in webhook requests using your shared secrets to confirm authenticity.
• Use HTTPS: Secure webhook endpoints with HTTPS to encrypt data in transit.
• Validate Source IP Addresses: Restrict your webhook endpoint to only accept requests originating from Yellow Card’s published public IPs. This prevents unauthorized sources from attempting to spoof webhook calls.

Use Unique Endpoints

Description: Designate a unique URL for receiving webhook notifications.

Best Practices:

• Restrict Access to Authorized IPs: Limit access to the webhook endpoint to only Yellow Card and any other authorized IP addresses.
• Use a Dedicated Webhook Endpoint: Designate a specific endpoint solely for receiving Yellow Card webhook notifications. This helps isolate webhook processing, reduce exposure, and simplify monitoring and access control.

Handle Webhook Data Securely

Description: Process and store webhook data securely to prevent tampering or leakage.

Best Practices:

• Log Webhook Payloads: Log only the necessary metadata (e.g., timestamp, event type, request ID) and ensure any sensitive fields within webhook payloads are redacted before logging
• Sanitize and Validate Incoming Data: Ensure all incoming data is sanitized and validated to prevent injection attacks. If the request appears tainted, please escalate to Yellow Card.

5. Logging and Monitoring

Description: Implement comprehensive logging and monitoring practices to detect abnormalities, support troubleshooting, and ensure the integrity of your integration with Yellow Card’s API.

Best Practices:

• Log Non-Sensitive Metadata: Record only essential, non-sensitive metadata (e.g., timestamps, request IDs, event types) for operational visibility.
• Redact Sensitive Information: Ensure any sensitive or regulated data is redacted, masked or omitted before writing to logs.
• Protect Log Access: Store logs securely, ensure immutability and restrict access to authorized personnel only

6. Secure Communications

Description: Ensure that your webhook endpoints use strong SSL/TLS configurations to protect data transmitted between Yellow Card and your systems.

Best Practices:

• Use TLS 1.2 or Higher: Configure your webhook endpoint to accept only TLS 1.2 or higher for all inbound HTTPS connections, and explicitly deny downgrade attempts.
• Disable Insecure Protocols and Ciphers: Remove outdated or weak protocols and cipher suites from your server configuration to prevent downgrade attacks and interception.
• Enable Perfect Forward Secrecy (PFS): Ensure your webhook TLS configuration supports PFS to enhance the security of encrypted communications.

By adhering to these best practices, you can enhance the security of your integration with Yellow Card's API, safeguarding sensitive information and ensuring compliance with industry standards.