Integrating third-party payment gateways allows businesses to securely outsource payment processing. These gateways handle sensitive data like cardholder information and offer reduced PCI DSS scope if integrated correctly.
However, insecure integration can lead to severe vulnerabilities—ranging from payment spoofing and order manipulation to fraud and business logic flaws. This cheat sheet outlines secure practices for integrating any third-party payment gateway, focusing on a general flow. It identifies potential failure points at each step and provides practical recommendations to prevent common mistakes.
A typical third-party payment flow consists of five core steps:
-
Cart Preparation
The user selects items and initiates checkout. -
Order Initialization (Merchant Backend → Payment Gateway)
The merchant backend creates a transaction or order via API and receives anorder_idorpayment_url. -
User Redirection to Payment Gateway
The user is redirected to the gateway-hosted payment page. -
Payment Execution (User → Gateway)
The user completes or fails the payment. -
Return and Verification (Payment Gateway → Merchant)
The user is redirected to the merchant site (callback/return URL), and optionally, the gateway sends a server-to-server notification. The merchant verifies the result and proceeds with order fulfillment.
The following sequence diagram explains the steps above.
Risks:
- Price tampering or product substitution via client-side manipulation.
- Missing server-side cart validation.
Mitigations:
- Validate all cart details (product IDs, prices, discounts) on the backend.
- Recalculate totals server-side using trusted data before order creation.
Risks:
- Trusting unauthenticated or spoofed callbacks.
- Processing orders before verifying payment status.
- Race conditions from multiple callbacks.
- Replaying callbacks to trigger repeated fulfillment (e.g., multiple shipments, account credits).
- Assuming user redirection parameters are trustworthy (these are untrusted and can be manipulated).
Mitigations:
- Validate all cart details (product IDs, prices, discounts) on the backend.
- Always verify the payment status server-side with the gateway’s API before fulfilling the order.
- Match the expected amount, currency, and order ID.
- Validate the authenticity of callbacks (e.g., HMAC signatures, secret tokens).
- Implement idempotency: only process an order once regardless of how many times the callback is received.
- Treat checkout expiry separately from webhook signature freshness. Gateways can retry delivery or send events out of order; verify late notifications and reconcile the current payment state instead of discarding them solely because the checkout expired. Use persistent duplicate-event records and idempotent fulfillment as described in the Webhook Security Cheat Sheet.
- Only server-to-server callbacks should be trusted for payment verification and order fulfillment.
- Log all callback attempts for forensic analysis.
Why it matters: Even with proper validation and logic, monitoring is crucial for detecting abuse, fraud attempts, or system misbehavior.
Recommendations:
- Log all payment attempts (initiation, redirects, callbacks) with timestamps and IPs.
- Alert on:
- Unexpected order statuses (e.g., "Paid" without any gateway confirmation).
- Excessive callback attempts for the same order.
- Payment failures followed by repeated attempts with identical data.
- Log callback identifiers, validation outcomes, and order correlation data instead of raw headers and bodies. Exclude credentials and unnecessary personal or payment data; apply the Logging Cheat Sheet's data-exclusion guidance.
- Do not retain sensitive authentication data, such as card verification codes or PIN data, after authorization, even if encrypted. Restrict access to permitted investigation records and define their retention period.
- Incorporate fraud and risk scoring mechanisms to detect carding attacks and other suspicious activities during payment execution.