Getting a payment gateway to authorize a test transaction is the easy part. Building a production-ready payment integration that handles tokenization correctly, stays within PCI scope, fires webhooks reliably, manages recurring billing, and doesn't create chargeback liability through avoidable implementation gaps takes considerably more thought than the basic API documentation covers.
This checklist is for developers integrating a payment gateway for the first time or auditing an existing integration before a production launch. It covers the decisions and implementation details that determine whether your integration is genuinely secure and compliant, not just technically functional.
1. Card Data Collection: Never Touch Raw PANs
The foundational decision in any payment gateway integration is how card data gets from the customer's browser to the gateway. The answer that keeps you out of PCI scope trouble: the card data should never touch your server. In payment industry terminology, the full 16-digit credit card number is called the Primary Account Number, or PAN. Keeping the PAN off your server is the single most important thing you can do to limit your PCI compliance exposure.
Hosted tokenization approaches accomplish this in two ways:
Hosted fields (iFrame tokenization). The card number, expiry, and CVV fields on your checkout page are rendered inside iFrames hosted by the gateway, not your own HTML. The customer types directly into the gateway's iFrame. When your checkout form submits, the gateway returns a one-time token that your server receives instead of the card data. Your server never sees the PAN. CyoGate's Collect.js implementation handles this approach — the developer portal has full integration documentation.
Hosted payment page redirect. The customer is redirected to a payment page hosted entirely on the gateway's domain to enter card data, then redirected back to your site after the transaction. This approach reduces your PCI scope to near zero but gives you less control over the checkout experience.
Either approach is vastly preferable to receiving raw card numbers on your server and then passing them to the gateway API. That pattern puts your entire server environment in PCI scope for the most demanding compliance assessment levels.
2. PCI Compliance Scope: Know Which SAQ You're In
PCI DSS compliance requirements depend on how your integration handles card data. The Self-Assessment Questionnaire type that applies to you determines what controls you need to have in place.
With hosted fields (Collect.js or equivalent): SAQ A. The lightest compliance path. Your iFrame implementation needs to meet PCI DSS 4.0's new script management requirements (Requirement 6.4.3 — all payment page scripts must be authorized and integrity-checked), but your server environment has minimal scope.
With a hosted redirect: SAQ A as well, with even less merchant-side scope since no payment page elements live on your domain.
With direct API integration that passes card data through your server: SAQ D, the most demanding questionnaire covering your entire server environment. Avoid this path unless you have a compelling reason and the compliance infrastructure to support it.
Our post on PCI DSS 4.0 checkout page requirements covers the specific script management requirements that became mandatory in March 2025 and apply to any checkout page that hosts payment fields.
3. Sandbox Testing: What to Actually Test
Most gateway documentation provides sandbox credentials and a set of test card numbers. Running a successful test authorization is the minimum, not the goal. Before going live, test the full range of scenarios your integration will encounter in production:
Authorization and capture: Both combined auth-capture and separate authorize-then-capture flows. If you ship before charging, you need auth-only with capture on shipment — test that the auth doesn't expire before capture in your fulfillment timeline.
Declines: Test declined authorizations and make sure your checkout handles them gracefully. The customer should see a useful message and be able to retry, not an unhandled exception.
Refunds and voids: Same-day voids vs. settled transaction refunds behave differently. Test both. Partial refunds if your business model requires them.
AVS and CVV responses: Test what happens when AVS returns a partial match or a no-match result. If your fraud rules reject on AVS mismatch, make sure that rejection path works correctly and the customer sees an appropriate message.
Webhooks: If your integration relies on webhook notifications for payment confirmation rather than synchronous API responses, test that your webhook endpoint receives and processes notifications correctly, handles duplicate events (gateways sometimes retry), and responds with the appropriate status code so the gateway doesn't keep retrying.
Recurring billing: If your integration includes subscription or installment billing, test the full recurring transaction flow including the initial credential-on-file storage, subsequent merchant-initiated transactions, failed payment handling, and the account updater process if the gateway supports it.
4. Fraud Rules: Configure Before You Go Live
Gateway-level fraud screening is not a set-it-and-forget-it configuration. The rules need to be calibrated for your specific transaction profile before you go live. Overly aggressive rules create false positives that decline legitimate customers. Absent or permissive rules let fraud through.
The baseline fraud rules worth configuring on any ecommerce integration:
CVV verification: Decline or flag transactions where CVV is not provided or does not match. A cardholder with a legitimate card always has the CVV. Transactions without a matching CVV are a fraud signal.
AVS verification: Decide how your integration handles AVS results. Full match (address and zip) is the strongest signal; no match is a fraud indicator. For international cards, AVS response behavior varies — configure your rules accordingly.
Velocity rules: Limit the number of transactions from the same card, same IP address, or same email address within a defined time window. Card testing attacks run many small transactions rapidly — velocity limits catch this pattern before significant fraud accumulates.
Transaction amount limits: Set a per-transaction maximum consistent with your normal business. An unusually large transaction outside your typical range is a flag worth reviewing manually.
CyoGate's iSpy fraud prevention provides a rule-based screening interface where you configure these and additional rules specific to your merchant category. Our post on how iSpy fraud screening works covers the available rules and how to tune them without blocking legitimate customers.
5. Recurring Billing: Credential-on-File Requirements
If your integration stores cards for future use, either for subscriptions or one-click checkout, the card networks have specific requirements for how those stored credentials must be used. Getting this wrong creates compliance exposure and chargebacks.
The key requirements developers need to implement correctly:
Initial transaction flag: The first transaction that stores a card for future use must be flagged as a credential-on-file initial transaction. This signals to the issuer that the cardholder is agreeing to future charges.
Subsequent transaction flags: Every subsequent transaction that uses a stored credential must be flagged appropriately as either a merchant-initiated transaction (MIT) or a cardholder-initiated transaction (CIT). The distinction matters for dispute liability.
Subscription transaction identifiers: Recurring subscription transactions must include the original transaction ID from the initial credential storage, linking the recurring charge back to the cardholder's consent.
Excessive retry rules: Visa's excessive retry rule limits how many times you can retry a declined recurring transaction within a billing cycle. Exceeding the limit results in fines. Build retry logic that respects the limit and implements smart dunning (declining retry on hard declines like stolen card vs. retrying soft declines like insufficient funds).
Our post on setting up recurring billing correctly covers the full credential-on-file framework in detail.
6. Error Handling and Logging
Production payment integrations fail in ways that sandbox testing doesn't reveal. Network timeouts, gateway maintenance windows, and edge-case decline codes all need handling that keeps the user experience clean and gives your team visibility into what happened.
Log every API request and response with a unique transaction reference, the response code, and the timestamp. Do not log raw card data — if you're using hosted tokenization correctly, you shouldn't have it to log. But do log the token, the amount, and the full gateway response including any error codes. When something goes wrong in production, this log is what lets you diagnose it.
Handle timeouts explicitly. A request to the gateway API that times out is not the same as a declined transaction. Your code should not assume a timeout means the charge didn't go through — it may have. Design your flow to handle the ambiguous state gracefully, either by checking the transaction status via a status API call or by flagging the order for manual review.
7. Going Live Checklist
Before switching from sandbox to production credentials, run through this final verification:
Production API keys are stored securely (environment variables or a secrets manager, not hardcoded in source). Your billing descriptor has been set to a name the customer will recognize. Fraud rules have been reviewed and configured for production traffic. Webhook endpoints are live and tested against production. Your PCI SAQ has been completed for your integration type. A test transaction has been run on production credentials before real customer traffic is directed to the integration.
The CyoGate developer portal has full API documentation, Collect.js integration guides, and sandbox credentials for testing. If you have integration questions, our developer support team can help you work through implementation specifics before you go live.