Testing & Sandbox Mode

Use provider sandbox environments and test credentials to validate your integration without moving real money.

Stripe Test Mode

Stripe's test mode uses sk_test_... and pk_test_... keys. All test transactions are isolated from live data.

Test Cards

Use any future expiry date (e.g., 12/30) and any 3-digit CVC.

Test Webhooks

After a test payment, Stripe sends webhooks to your registered endpoint. You can also replay events manually from the Stripe Dashboard under Developers → Webhooks → [your endpoint] → Send test webhook.

To test locally, use the Stripe CLI:

stripe listen --forward-to https://webhook.yourcompany.com/hooks/stripe/{providerId}

On the hosted stack, use https://webhook.payment-gateway.app/hooks/stripe/{providerId} instead — Hostnames & DNS conventions.

GoCardless Sandbox

GoCardless provides a full sandbox environment at api-sandbox.gocardless.com. Create a sandbox account at sandbox.gocardless.com.

Use your sandbox Access Token when adding the provider and set Environment to sandbox.

The sandbox supports simulating mandate confirmations and payment clearing events via the GoCardless dashboard.

Simulating Webhook Events

To test your webhook handler without triggering a real payment:

Stripe (CLI)

# Simulate a succeeded payment
stripe trigger payment_intent.succeeded

# Simulate a refund
stripe trigger charge.refunded

Manual HTTP Test

You can POST a test payload directly to the webhook endpoint. Note that signature verification will fail unless you generate a valid signature — use the provider CLI tools or sandbox dashboards instead.

Testing Tax Calculations

To verify tax rules are applied correctly:

1. Create a checkout with a known buyer country (set billing address at checkout).
2. Confirm the checkout uses the expected tax treatment before payment.
3. After payment, the transaction record includes a full taxBreakdown field with rate, treatment, and legal reference.
4. For manual draft invoices, use the Admin Panel invoice editor or POST /api/v1/invoices/preview-tax to verify the same backend tax engine resolves the expected rate before saving.

Use the Admin Panel under Transactions → [transaction] → Tax Details to inspect transaction tax metadata, and under Invoices → Draft Invoice to inspect the previewed automatic invoice tax result.

Include at least these edge cases before moving tax changes to production:

• Mixed goods and digital-service baskets where billing and shipping countries differ, including EU/EU, EU/non-EU, and non-EU/EU combinations.
• Gross-price and net-price checkouts when automatic tax calculation is enabled.
• Refund, lost/accepted chargeback, and won-chargeback flows; won chargebacks should not remain as reportable tax reductions.
• Tax record rebuild after test data creation; Tax by country, Revenue by country, and VAT OSS should use active canonical tax records without UNKNOWN country rows.

Testing Recurring Schedules

Recurring schedules use nextRunDate as the next due date. To test without waiting for the scheduled job:

1. Create a schedule whose startDate materializes a due or past nextRunDate.
2. Run the Admin Panel Recurring -> Run Due Schedules action as a global administrator, or call POST /api/v1/system/recurring/process.
3. Run the processor a second time to verify the schedule does not generate duplicate invoices after nextRunDate advances.
4. Schedule a future cancellation with a reason and verify the schedule remains cancel_requested when due processing runs before effectiveFromCycle.
5. Verify customer/admin detail pages show Cancellation Scheduled, the effective date, requested-at timestamp, and reason.
6. Move effectiveFromCycle into the past in test data, run Run Due Schedules, and verify cancellationsFinalized increments without generating a new invoice for that cycle.

Engineering validation should also include the recurring smoke flow and the VM-backed recurring regression suite after the branch is committed and deployed.

Checking Logs

When something unexpected happens during testing:

# Admin backend logs
docker logs payment-gateway-admin-backend --tail 100 -f

# Main backend logs
docker logs payment-gateway-main-backend --tail 100 -f

# Worker logs (PDF generation)
docker logs payment-gateway-main-backend-worker --tail 50 -f

Set MPG_LOG_LEVEL=debug in your environment for verbose output during testing. Reset to error for production.