# Test Payments in Sandbox Mode

**Audience:** All users (Merchants, Developers, Testers)

**Environment:** Sandbox / Production

## Introduction

Testing your payment integration is crucial before processing real transactions from your customers. Our **Sandbox environment** provides a safe space to do this without involving real money. **Test cards** are special, non-functional card numbers you can use within the Sandbox to simulate various payment scenarios.

This guide explains what test cards are, why they're important, and how to use them effectively.

## What is Sandbox Mode?

Think of the Sandbox environment as a complete replica of our live production environment, but entirely isolated and using test data.

* **No Real Money:** Transactions processed here do not involve actual funds or real bank accounts.
* **Safe Testing:** You can test your integration, checkout flow, API calls, and error handling without any risk.
* **Simulate Scenarios:** Easily trigger successful payments, different types of declines, and error conditions.


Sandboxes can be selected from the navigation bar, otherwise you can create your first sandbox from the homepage of the Helix-Pay portal.

## What are Test Cards?

Test cards are specific card numbers provided by us (and the card networks like Visa, Mastercard, etc.) solely for testing purposes in a Sandbox environment.

* **Not Real Cards:** They don't correspond to any actual bank account or credit line.
* **Sandbox Only:** They will *only* work in our designated Sandbox/Test environment. They will be automatically declined if used in the live production environment.
* **Simulate Responses:** Different test card numbers are designed to trigger specific responses, such as:
  * Successful payment
  * Declined (Insufficient Funds)
  * Declined (Invalid CVC)
  * Declined (Expired Card)
  * Generic Decline
  * And more...


## Why Use Test Cards?

* **Safety:** Test your entire payment flow without the risk of charging real cards (yours or your customers').
* **Verification:** Confirm your integration correctly handles both successful payments and various error/decline scenarios.
* **User Experience:** Test the messages and redirects your customers see during different outcomes.
* **Compliance:** Ensure you're meeting requirements for handling payment responses.


## How to Use Test Cards

Using test cards is straightforward. Follow these steps:

1. **Ensure You're in Sandbox Mode:**
  * If using our dashboard, make sure you've selected a Sandbox (You will see a sandbox banner at the top of the page).
  * If using our API, ensure you are using your **Sandbox API Keys**. Live keys will not work with test cards (and attempting to use test cards in live mode may cause errors).
2. **Generate a Payment:**


* From the Portal
  * On the payments page, use the Create payment link button to create a new payment. Once created, you can copy the link to your clipboard and can navigate to integrate
  * When visiting the link, you should see a clear warning banner that this is a sandbox payment
* From the API
  * Using your **Sandbox API Key**, call the POST /payments endpoint with your test payment
  * Use the **checkout_url** response field to get the checkout link.


1. **Test Card Numbers:**
| Card Type | Number | CVV | Date |
|  --- | --- | --- | --- |
| Visa | `4000 0566 5566 5556` | any 3 digits | Any future date |
| Mastercard | `5555 5555 5555 4444` | any 3 digits | Any future date |
| Amex | `3782 822463 10005` | any 4 digits | Any future date |
| Declined | `4000 0000 0000 0002` | any 3 digits | Any future date |
2. **Enter Test Data in Your Checkout Form:**
  * During checkout in your Sandbox environment (whether on your website, app, or using a test tool), enter the test card details:
    * **Card Number:** Use one of the test card numbers from our documentation.
    * **Expiry Date:** Use any **future date**.
      * *Format:* MM/YY or MM/YYYY (e.g., `12/25` or `12/2025`).
      * *To test expired card scenarios:* Use any **past date** (e.g., `12/20`).
    * **CVC/CVV:** Use any **3 or 4-digit number** (depending on card type: 3 for Visa/Mastercard/Discover, 4 for Amex).
      * *Examples:* `123`, `999`, `1234`.
3. **Submit the Payment:** Complete the checkout process.
4. **Observe the Result:**
  * Check the response you receive in your application, the user interface, or the API response.
  * Verify that the outcome matches the expected result for the test card number you used (e.g., a success message, a specific decline error).


## Important Considerations

* **NEVER Use Real Card Numbers in Sandbox:** This exposes sensitive data unnecessarily.
* **Test Cards ONLY Work in Sandbox:** They are designed to fail in the live production environment.
* **No Funds Transferred:** Remember, no actual money is ever moved when using test cards in Sandbox.


## Further Reading

* [Integrations](/guides/integrations) - Connect your store or application using events


## Troubleshooting

If a test card isn't working as expected:

1. **Confirm Sandbox Mode:** Double-check you are definitely using the Sandbox environment and Sandbox API keys.
2. **Verify Card Number:** Ensure you typed the test card number correctly.
3. **Check Expiry/CVC:** Make sure you're using a future expiry date (unless testing expiration) and a valid CVC format.
4. **Consult Documentation:** Refer to our specific test card list to ensure the number you used is intended for the outcome you expect.
5. **Check API Logs:** If using the API, review the request and response logs for detailed error messages.


If you continue to have issues, please contact our support team.

By using our Sandbox environment and test cards effectively, you can build confidence in your payment integration and ensure a smooth experience for your customers when you go live. Happy testing!