From Sandbox to Production: Shipping Your Payment Integration

A payment gateway integration is not complete when the first sandbox transaction succeeds. It is complete when your application can collect payment information, handle failures, process asynchronous events, reconcile unknown outcomes, and move to production without changing its core payment logic.

This walkthrough follows the developer journey from a test merchant to controlled live processing. Use it when your team is mid-integration and needs a practical path to launch through a developer sandbox environment.

1. Start With the Sandbox Test Merchant

Begin by separating payment development from production operations. Create or request access to the sandbox test merchant, then confirm that your team can access the required credentials, test values, developer portal, and integration documentation.

The Integrate Payments developer sandbox provides a test merchant for learning the payment gateway and testing application code before live processing.

Confirm these items before writing transaction logic:

• Sandbox credentials and environment configuration.
• Public and private key responsibilities.
• Test payment values and response conditions.
• Supported transaction types.
• Return or redirect behavior.
• Webhook configuration requirements.
• Customer Vault and recurring billing documentation.
• Available support channels for integration questions.

‍

Keep sandbox and production configuration separate from the beginning. Use environment variables or configuration management rather than hard-coding credentials into the application.

Review the developer documentation for current field names, test values, response formats, and supported workflows. Do not infer implementation details from examples intended for a different integration model.

2. Build the First End-to-End Transaction

Next, build one complete payment path. Do not begin with isolated API calls that are difficult to connect later.

A typical flow includes:

1. Display payment fields or a hosted payment page.
2. Collect payment information through the selected gateway-controlled method.
3. Tokenize payment information when the integration supports client-side tokenization.
4. Send the payment reference and order data to your backend.
5. Validate the amount and order details server-side.
6. Submit the transaction using private backend credentials.
7. Process the documented gateway response.
8. Receive the return or redirect confirmation.
9. Update the internal order only after verifying the payment state.

‍

Keep business logic in your application and sensitive payment collection in the appropriate gateway-controlled layer. Your frontend should not determine the final amount, and private credentials should never be exposed in browser code.

The browser response is useful for customer experience, but it should not be the only source of truth. A payment may continue processing after the browser has closed, the network has failed, or the customer has been redirected.

Model payment states explicitly. Use states such as pending, authorized, captured, declined, voided, refunded, and reconciliation_required instead of relying on a single is_paid value.

For a broader implementation walkthrough, see How to Integrate Payments Into Custom Software.

3. Test the Failure Paths

A successful sale confirms only one branch of your integration. Before adding production credentials, test how your application behaves when the gateway, customer, or network produces an unexpected result.

Test the following scenarios:

Payment Responses

• Declined payment.
• Invalid payment data.
• Expired payment token.
• AVS response variations.
• CVV response variations.
• Authorization without capture.
• Sale submitted for settlement.
• Void after authorization or an unsettled transaction.
• Full refund.
• Partial refund.
• Refund failure.

‍

Display a clear customer-facing message while keeping detailed gateway responses in restricted operational logs. Do not expose raw response text when it could reveal sensitive or confusing implementation details.

Network and Event Failures

Simulate gateway timeouts and lost responses. If your server submits a transaction but does not receive a definitive answer, do not immediately submit a second transaction. Mark the payment as unknown and use the documented lookup or reconciliation process before retrying.

Test duplicate webhook delivery and invalid webhook signatures. Your application should ignore an already-processed event and reject an event that fails verification.

This is also the point to test authorization, capture, void, and refund permissions. Restrict administrative actions to approved roles and link every refund to the original payment and internal order, especially when planning payment platform integration for apps and marketplaces.

4. Add Tokenization and Customer Vault Testing

Once the one-time payment path works, test stored payment references. Tokenization allows your application to use a payment reference without storing the original payment information in your own database.

The Customer Vault integration supports storing payment information in a secured gateway environment and referencing it for future transactions. Confirm the exact creation and update process in the current documentation.

Test this sequence:

1. Create a customer reference.
2. Add or tokenize a payment method.
3. Process a transaction using the stored reference.
4. Confirm that your database stores only the permitted reference and metadata.
5. Simulate an expired payment method.
6. Replace or update the payment method.
7. Confirm that the customer record remains separate from payment method status.

‍

Store internal customer IDs, gateway references, transaction IDs, subscription IDs, card brand, and last-four information only when returned and needed. Do not store full card numbers, CVV values, or raw payment requests and responses.

5. Test Recurring Billing Separately

Recurring billing is a separate workflow, not a variation of a one-time sale. Your application must manage the customer’s consent, plan, billing cycle, renewal state, payment method, cancellation status, and failed renewal process through a recurring billing payment gateway API.

Test the complete lifecycle:

• Create a subscription.
• Configure the plan and billing cycle.
• Store the subscription and customer references.
• Process a renewal through the documented event flow.
• Update internal records from renewal webhooks.
• Handle a failed renewal.
• Notify the customer when action is required.
• Update the payment method.
• Cancel the subscription.
• Prevent future renewals after cancellation.

‍

Use the original transaction and customer references where required for stored-credential processing. Keep subscription state separate from payment state because an active subscription can have a failed renewal, and a customer can have more than one payment method. For a deeper implementation example, review this article on recurring billing payments API for custom software.

6. Harden the Webhook Handler

Webhooks provide asynchronous updates for renewals, refunds, settlements, disputes, and delayed transaction results. Treat the webhook endpoint as a security-sensitive payment component.

Your handler should:

• Use an HTTPS endpoint in production.
• Preserve the raw request body when signature verification requires it.
• Verify the gateway signature before processing the event.
• Validate the event structure.
• Persist the event ID or unique transaction reference.
• Reject invalid signatures.
• Ignore duplicate events safely.
• Place accepted events into a durable queue.
• Process events asynchronously.
• Retry temporary failures.
• Reconcile events against internal orders and customers.

‍

The Integrate Payments webhook and integration resources document the required endpoint configuration, signature verification process, event structure, and delivery behavior. Follow those documented requirements for your integration.

Return a successful HTTP response after the event has been safely recorded. Do not perform slow fulfillment, reporting, or customer-notification work before acknowledging the request. This pattern also supports scaling custom web application ecommerce with a flexible payment API.

7. Prepare the Production Cutover

Production cutover should change environment configuration, not payment behavior. Use a feature flag or deployment configuration to direct the tested integration to production credentials and production endpoints.

Complete these actions:

• Confirm the merchant account and processor configuration.
• Replace sandbox credentials with production credentials.
• Move private keys into a managed secrets system.
• Restrict key access by environment and service.
• Configure production webhook secrets.
• Enforce HTTPS.
• Confirm allowed domains and return URLs.
• Remove sensitive values from logs, traces, and analytics.
• Restrict capture, void, refund, and reporting permissions.
• Confirm the production settlement and reporting process.
• Document the applicable PCI scope and SAQ process.

‍

Tokenization and hosted payment components can reduce the payment data entering your environment, but they do not automatically determine PCI compliance. Review this guide to PCI security for payment API integration, then confirm the applicable requirements with your acquirer, qualified security assessor, or compliance provider.

8. Go Live With a Controlled Transaction

Do not treat the first production deployment as a volume launch. Start with a small, controlled live transaction using an approved internal or pilot customer.

Verify each record across the system:

• Gateway response.
• Internal payment record.
• Webhook event.
• Order or account state.
• Settlement or reporting record.
• Customer receipt or confirmation.
• Refund capability.

‍

After the first transaction, monitor declines, gateway errors, refund activity, disputes, webhook failures, and settlement differences. Keep the team available to pause new transactions if internal records and gateway records diverge.

9. Reconcile After Launch

Reconciliation is the production feedback loop. Webhooks can be delayed, duplicated, or missed, and a synchronous API response can be lost during a network interruption.

Run scheduled checks that compare:

• Internal orders with gateway transactions.
• Captured payments with refunds.
• Gateway transactions with settlement reports.
• Subscription renewals with customer entitlements.
• Refund records with the original captured amount.

‍

Use separate identifiers for orders, payments, refunds, disputes, subscriptions, customers, and settlements. When records do not match, set a reconciliation_required state and route the record for review rather than silently overwriting it.

Sandbox-to-Production Checklist

Before enabling live payments, confirm that your team has:

• Accessed the sandbox test merchant.
• Reviewed current developer documentation.
• Separated sandbox and production configuration.
• Completed an end-to-end test transaction.
• Tested declines and invalid payment data.
• Tested AVS and CVV responses.
• Tested authorization, capture, sale, and void behavior.
• Tested full and partial refunds.
• Tested timeouts and unknown outcomes.
• Tested duplicate and invalid webhook events.
• Verified webhook signatures.
• Added event persistence and idempotent processing.
• Tested Customer Vault creation, reuse, and replacement.
• Tested subscription creation, renewal, failure, and cancellation.
• Removed sensitive values from logs.
• Stored production secrets in a managed system.
• Confirmed domains, return URLs, and HTTPS.
• Verified merchant account and processor configuration.
• Completed a controlled live transaction.
• Confirmed settlement and reporting.
• Scheduled post-launch reconciliation.

‍

Common Mistakes to Avoid

Treating Test Data as Production Data

Sandbox values, test credentials, sample tokens, and test merchant records belong only in development and test environments. Keep them out of production configuration, customer records, monitoring dashboards, and operational reports.

Treating a Synchronous Response as the Final Answer

A request can time out after the gateway receives it. A browser can close before a redirect completes. Use webhooks, transaction lookup, and reconciliation to resolve unknown outcomes.

Processing Webhooks Without Idempotency

The same event may be delivered more than once. Persist event identifiers and protect fulfillment, account activation, refunds, and ledger updates against duplicate processing.

Changing Payment Logic During Cutover

Production should use the same tested payment state model and error handling as sandbox. Change credentials, endpoints, secrets, domains, and merchant configuration: not the core transaction logic.

Discuss Your Integration Plan

If your team is stuck between the first sandbox transaction and production launch, bring your application stack, integration model, payment flows, and target timeline to an integration discussion. You can contact the Integrate Payments integration team to review your plan.

Start with the developer sandbox, review the Customer Vault payment workflow, and use the documented requirements to plan a controlled path to live processing.

Compliance disclosure: Payment integrations remain subject to applicable processor, card-brand, regulatory, and PCI DSS requirements. Completing a Self-Assessment Questionnaire does not by itself establish compliance for every implementation. Confirm your obligations with your acquirer, qualified security assessor, or compliance provider.