Skip to main content
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 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 for quick testing
    • Or set up a local development endpoint with ngrok 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 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

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.
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.

​
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 for easy webhook inspection
  • Support: Reach out to HitPay support team through your dashboard