Skip to content

How to Use the 4Geeks Payments Sandbox Environment for Testing

🤖 Explain with AI

Deploying payment logic directly to a live environment carries significant risks, such as accidental charges to real credit cards and cluttered financial reporting. The 4Geeks Payments Sandbox provides a safe, isolated replica of your production environment. It allows developers and finance managers to simulate transactions, test API integrations, and validate complex billing workflows using 4Geeks Payments without moving actual money.

This article guides you through accessing the sandbox, obtaining test credentials, and performing simulated transactions to ensure your system is ready for launch.

Prerequisites

Before you begin testing, ensure you have the following:

  • 4Geeks Console Access: You must have an active account with access to the 4Geeks Console.
  • Permissions: You need “Developer” or “Admin” level permissions to view API keys and toggle environment modes.
  • Payment Integration: Ideally, you should have a basic understanding of how your application connects to 4Geeks Payments, or be ready to test manual transactions via the dashboard.

Step-by-Step Instructions

Follow these steps to configure and utilize the sandbox environment effectively.

Step 1: Switch to Test Mode

The 4Geeks platform separates “Live” data from “Test” data to prevent accidents.

  1. Log in to the 4Geeks Console.
  2. Navigate to the Payments module on the left-hand sidebar.
  3. Locate the Environment Toggle in the top navigation bar (usually displaying “Live”).
  4. Click the toggle to switch it to “Test” or “Sandbox”.
  5. The dashboard banner should change color (typically to orange or blue) to indicate you are now working with dummy data.

Step 2: Obtain Test API Credentials

Your live API keys will not work in the sandbox. You must generate specific credentials for testing.

  1. While in Test Mode, go to Settings > API & Webhooks.
  2. Locate the Public Key and Secret Key sections.
  3. Click Reveal Keys to view your test credentials. These keys usually start with a prefix like pk_test_ or sk_test_.
  4. Copy these keys and update your local development environment or staging server configuration.

Note: Never use your Live keys (pk_live_...) in your testing code, as this will result in failed authentication or unintended real transactions.

Step 3: Simulate a Transaction

You can verify your integration by processing a payment using test card numbers.

  1. Initiate a payment flow through your application (e.g., a checkout page or invoice payment link).
  2. When prompted for payment details, use one of the 4Geeks Test Card Numbers. (See the 4Geeks Payments documentation for a full list).
    • Visa (Successful): 4242 4242 4242 4242
    • Mastercard (Declined): 5100 0000 0000 0051
    • Expiry Date: Any future date.
    • CVC: Any 3 digits (e.g., 123).
  3. Complete the checkout process.

Step 4: Verify the Results

  1. Return to the 4Geeks Console (ensure you are still in Test Mode).
  2. Click on the Transactions tab.
  3. You should see your most recent simulated payment listed.
  4. Click the transaction ID to view details, including the status (Succeeded/Failed), raw API response logs, and associated metadata.

Common Use Cases

Scenario 1: Testing Automatic Dunning for Subscriptions

If you use 4Geeks Payments to manage recurring billing, you can simulate a failed payment to test your dunning (retry) logic.

  • Action: Create a subscription in the sandbox using a specific “Decline” test card number.
  • Validation: Verify that the system attempts to retry the payment according to your schedule and that the correct “Payment Failed” email notification is triggered to the dummy customer email.

Scenario 2: Validating Payroll Disbursements

For companies using 4Geeks Payroll, the sandbox is essential for testing contractor payouts.

  • Action: Set up a test contractor profile and initiate a bulk payout using test funds in your virtual wallet.
  • Validation: Check that the transaction status updates to “Paid” in the console and that the corresponding webhook is fired to your backend system, confirming the integration handles payouts correctly.

Troubleshooting

Issue 1: “Invalid API Key” Error

  • Cause: You are likely using your Live API keys while your application is pointing to the Sandbox endpoint, or vice versa.
  • Solution: Check your .env file or configuration settings. Ensure your keys match the environment (Test keys for Sandbox, Live keys for Production).

Issue 2: Transactions are not appearing in the Dashboard

  • Cause: The console view might be set to the wrong mode.
  • Solution: Look at the toggle switch in the header of the 4Geeks Console. If you processed a test transaction, ensure the toggle is set to Test. Live transactions will never appear in the Test view.

Issue 3: Webhooks are not triggering

  • Cause: Webhook endpoints must be configured separately for Live and Test environments.
  • Solution: Go to Settings > API & Webhooks while in Test Mode. Ensure your staging server URL is added as a webhook endpoint and that the “subscription_created” or “payment_succeeded” events are enabled.

Conclusion

Utilizing the 4Geeks Payments Sandbox is a critical step in the development lifecycle. It ensures that your billing logic, from patient invoicing in 4Geeks Health to subscription management in 4Geeks Assets, functions flawlessly before you interact with real customers. By isolating tests in this environment, you protect your revenue streams and maintain clean data for accurate reporting.

For more advanced testing scenarios, such as 3D Secure simulation or dispute handling, please refer to the Additional Resources below.

Additional Resources