How to use the 4Geeks Payments Sandbox environment for testing

The 4Geeks Payments Sandbox is a safe, isolated environment designed for developers and administrators to test integrations without moving real money. It allows you to execute unlimited simulations to ensure your business logic handles every scenario correctly—such as successful charges, declined cards, and refunds—before going live.

Data created in the Sandbox is distinct from Production data, ensuring your financial records remain clean during development.

Prerequisites

• A verified 4Geeks account.
• Access to the 4Geeks Console (https://console.4geeks.io).
• Basic familiarity with API requests (if integrating via code).

Start Accepting Online Payments in 5 Minutes

Get paid faster on your website, your platform or social media via our payment link. Multiple currencies. 100% secure. 5-min activation process.

Learn more

How to Use the Sandbox Environment

1. Access Your Sandbox API Keys

To interact with the Sandbox, you must use a specific set of API keys different from your production keys.

1. Log in to the 4Geeks Console.
2. Navigate to the Developers or API Keys section in the side menu.
3. Locate the keys labeled Test.
   • Test Secret Key: Starts with sk_test_...
   • Test Public Key: Starts with pk_test_...
4. Copy these keys. Crucial: Never use your Live keys (sk_live_...) for testing, as this may incur real charges.

2. Configure Your Integration

Update your application's configuration to use the Test Keys you just copied. If you are using the 4Geeks Payments SDK or making direct HTTP requests, ensure the Authorization header uses the test key.

Example Request (cURL):

curl -X POST https://api.4geeks.io/v1/payments/ \
  -u sk_test_51O62xYzAbcDef123: \
  -d amount=10.00 \
  -d currency=USD \
  -d description="Test Charge"

3. Simulate Transactions using Test Cards

In the Sandbox, real credit card numbers will not work. Instead, 4Geeks Payments provides specific test card numbers that trigger predefined behaviors.

Standard Test Card (Always Successful):

4. Verify in the Dashboard

After sending a test transaction:

1. Return to the 4Geeks Console.
2. Ensure you have toggled the view to "Test Mode" or "Sandbox" (usually found in the top navigation bar or settings).
3. Navigate to Transactions or Sales.
4. You should see your simulated payment listed with a status of Paid or Pending.

Common Use Cases

Scenario 1: Simulating a Successful Checkout flow

Goal: Verify that your website redirects users correctly after a purchase.

1. Create a payment request using your sk_test_... key.
2. Use the returned URL to open the payment page.
3. Enter the Visa test card (4242...) and any future expiry date.
4. Complete the payment.
5. Result: The system should redirect you to your success_url, and the webhook for payment.succeededshould fire.

Scenario 2: Handling Declined Transactions

Goal: Ensure your app displays the correct error message when a card is rejected.

1. Initiate a payment flow as usual.
2. Use a specific "Force Error" test card (e.g., specific numbers provided in the documentation for "Insufficient Funds").
3. Result: The API will return a 402 Payment Required or similar error code. Your application should catch this and display a "Payment Declined" message to the user instead of crashing.

Troubleshooting

• Issue 1: "Invalid API Key" Error
  • Cause: You may be using a Live key in a Test environment or vice versa, or the key was copied incorrectly.
  • Solution: Check the prefix of your key. It must start with sk_test_ for Sandbox requests.
• Issue 2: Transaction not appearing in Console
  • Cause: You might be looking at the Live data view while making Test transactions.
  • Solution: Toggle the "View Test Data" switch in your 4Geeks Console header to see Sandbox activity.
• Issue 3: Real card was declined
  • Cause: Real credit cards cannot be processed in the Sandbox environment.
  • Solution: Use the standard test card numbers provided above.

FAQs