> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitpayapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing in Sandbox

> Learn how to test in-person payment integrations in the HitPay Sandbox environment

Before moving to production, you should thoroughly test your in-person payment integration in the Sandbox environment. This guide will walk you through the testing process for both card and QR code payments.

## Prerequisites

1. **Sandbox API Keys**: Obtain your Sandbox API key and Salt value from your HitPay dashboard
   * Navigate to your Sandbox account settings
   * Go to **API Keys** section
   * Copy your **Business API Key** and **Salt** value

2. **Terminal Setup**: Ensure your Wi-Fi terminal is properly configured and connected
   * Follow the [Setup Your Reader](/apis/guide/in-person-payments/overview#setup-your-reader) instructions
   * Verify the terminal is in **In-Person Payment API** mode
   * Confirm the terminal is connected to the internet

3. **Webhook Endpoint**: Set up a test webhook endpoint to receive payment notifications
   * Use a tool like [webhook.site](https://webhook.site) for quick testing
   * Or set up a local development endpoint with [ngrok](https://ngrok.com) for tunneling

## Testing Successful Card Payments

To test successful card payments in Sandbox, you need a **physical test card**:

1. **Obtain Test Cards**: Contact HitPay support to request physical test cards for your region
   * Test cards simulate various payment scenarios
   * Different cards test different card networks (Visa, Mastercard, etc.)

2. **Test Payment Flow**:
   * Create a payment request using the Sandbox API endpoint: `https://api.sandbox.hit-pay.com/v1/payment-requests`
   * Use `wifi_card_reader` as the payment method
   * Specify your test terminal ID (`wifi_terminal_id`)
   * Include your webhook URL
   * Present the physical test card to the terminal
   * Complete the payment on the terminal
   * Verify the webhook is received with `status=completed`

3. **Verify Webhook**: Check that your webhook endpoint receives:
   * Payment status as `completed`
   * Correct `payment_request_id`
   * Valid HMAC signature

## Testing QR Code Payments

QR code payments are easier to test as they don't require physical test cards:

1. **Create QR Payment Request**:
   * Use a supported QR payment method (e.g., `paynow_online` for Singapore)
   * Set `generate_qr` to `true`
   * Use your Sandbox API endpoint

2. **Scan QR Code**:
   * The terminal will display the QR code
   * Use a mobile payment app that supports the QR payment method
   * Scan the QR code and complete the payment

3. **Verify Payment**:
   * Check your webhook endpoint receives the successful payment notification
   * Verify the payment details match your request

## Testing Failed Payments

To test failed payment scenarios:

1. **Card Decline Testing**:
   * Use a test card configured to decline (if available from HitPay)
   * Attempt a payment that will be declined
   * Verify your webhook handler receives `status=failed`
   * Check that the `error_message` is properly displayed
   * See [Handling Failed Payment Requests](/apis/guide/in-person-payments/failed-payments) for detailed implementation

2. **Timeout Testing**:
   * Simulate network issues or delays
   * Allow payment to timeout
   * Verify failed webhook is received

3. **Cancellation Testing**:
   * Start a payment on the terminal
   * Cancel the payment before completion
   * Verify your application handles the cancellation properly

## Testing Checklist

Before moving to production, ensure you've tested:

* [ ] Successful card payment flow
* [ ] Successful QR code payment flow
* [ ] Failed payment webhook handling
* [ ] Webhook HMAC signature validation
* [ ] Error message display to users
* [ ] Payment request status updates in your system
* [ ] Terminal connection and activation
* [ ] Multiple payment methods (if applicable)

## Important Testing Notes

<Warning>
  In-person payment APIs in Sandbox require physical hardware (terminals and test cards or QR payment apps). There is currently no simulator or virtual testing environment available. All testing must be done with real terminals connected to the Sandbox environment.
</Warning>

<Info>
  For testing QR payments, you can use your personal mobile payment apps (if they support the payment method) as long as you're using the Sandbox environment. Transactions won't result in actual charges in Sandbox.
</Info>

## Getting Help with Testing

If you need assistance with testing:

* **Test Cards**: Contact HitPay support to obtain physical test cards
* **Terminal Issues**: Check terminal connectivity and ensure it's properly registered
* **Webhook Testing**: Use [webhook.site](https://webhook.site) for easy webhook inspection
* **Support**: Reach out to HitPay support team through your dashboard

## Related Documentation

* [In-Person Payments Overview](/apis/guide/in-person-payments/overview) - Learn the basics of in-person payments
* [Handling Failed Payment Requests](/apis/guide/in-person-payments/failed-payments) - Implement failed payment handling