Testing Workflows in your Sandbox

Use this document to map outbound transaction payloads to expected results in the Stax sandbox environment. A sandbox account is intended solely for mock data, and no transactions processed in a sandbox environment are routed through a real Merchant ID (MID). This guide covers testing for Stax Sandbox accounts configured with test gateways (ACH (bank accounts) and CC(credit cards)). Sandbox testing does not account for testing performed on live merchant accounts, regardless of their purpose. The mock payment gateway alters behaviour based on the combination of the payment method and the total amount.

Successful Tokenization (Storing Payment Methods)

You can test the tokenization and storage of payment methods (cards/ACH) on file independently of an immediate payment transaction.
Any combination of credit card or ACH data that passes basic validation (Luhn check for cards) will succeed in tokenizing the payment method.

Successful Payment Scenarios

Use these test scenarios to verify baseline authorization for credit cards and ACH payments. Unless otherwise noted, any standard transaction amount will process successfully. Ensure that card expiration dates are in the future and CVV lengths are valid to pass front-end checks. Note that other combinations of card numbers and routing/account numbers may also trigger successful payment tests.

Credit Card Specifics (AVS, CVV, and Stored Credentials)

• AVS (Address Verification Service) / CVV (Card Verification Value) Verification: Sandbox accounts do not validate AVS or CVV, so it is not possible to trigger AVS or CVV failures in the test environment (aside from basic CVV length checks). In production, however, payments may fail if this data is missing or invalid.
• Stored Credentials: While the sandbox environment does not validate these values, integrators should pass them in all sandbox requests to prepare for production. In production, including these values is mandatory to avoid card-brand payment failures, as they define how the payment is used and who initiates it. See Storing Payment Methods for the required fields, and Best Practices for guidance on stored credentials and recurring payments.

Credit Card Success Credentials

For each card, you can use any dollar amount. The API message will be empty with a success status.

Debit Card Success Credentials

This card test verifies debit-specific routing rails. Debit card testing is a required testing component for integrations that are building surcharging capabilities.

For each card, you can use any dollar amount. The API message will be empty with a success status.

ACH Success Credentials

For each card, you can use any dollar amount. The API message will be empty with a success status.

Payment Failure Testing

Immediate Payment Failure Scenarios

These scenarios trigger immediate gateway-level failures. Because payments can fail for various reasons, do not rely on specific error messages for business logic. Instead, surface the specific error provided in the API response's message field to the user.

For a declined card issue, the API status will be Fail with the API message, "gateway response: Declined".

For general payment errors, the API status will be Fail with the API message, "gateway response: Error".

For either message, display the error message and prompt the user to re-enter a valid payment method.

Connectivity Issues & Pending Statuses

These scenarios simulate network connectivity issues where the initial transaction status is unknown. To determine the final state, use API polling or listen for the update_transaction webhook event.
For PENDING transactions, do not treat the event as a hard failure, as the status may resolve. Because reattempts can lead to duplicate charges, we recommend displaying the following messaging to your customers:

Payment Pending: Please do not retry the transaction as it may cause duplicate charges. Your payment will update automatically. If it remains pending for more than 24 hours, please contact customer support.

While Stax monitors for final states, transactions should rarely remain PENDING. If a transaction remains in this state indefinitely, please contact support.

Use any valid success credit card or ACH method.

Both scenarios will respond with the message, "Gateway Unreachable".

Use webhooks (update_transaction) or poll the API to detect state transition.

For the self-resolving scenario, the transaction initiates in PENDING status and resolves to SUCCESS.

For the gateway request timeout scenario, the gateway connection hangs for 30 seconds. This scenario is intentionally designed to mimic a rare edge case where the payment remains PENDING. Status is unknown; however, do not treat it as a hard failure. Use webhooks or poll the API to detect the final state.

Post-Settlement & Asynchronous Lifecycle Scenarios

These test cases process as SUCCESS and retain that status while populating properties for testing downstream lifecycle scenarios. To trigger these state changes, you must select "Simulate Settlement" in the Deposit Report within Stax Pay or Stax Connect after the initial payment is created.

• Credit Card Disputes: Monitor via API polling or the create_dispute and update_dispute webhooks.
  • NOTE: Some live merchant accounts do not support this dispute functionality.
• ACH Rejections: Monitor via API polling or the update_transaction_settled and create_transaction webhooks to detect auto-voided child transactions and their funding.

Credit Card Chargeback Handling: Retain original success status; check for associated Dispute records in the API. Block refunds while a dispute is active to prevent double-crediting. Update internal transaction status to 'Disputed' until resolution.

ACH Rejection Handling: Original status remains 'Success'; check for a child_transaction (type: void). Stax will auto-void the transaction upon rejection (can occur days/months later). Block refunds to prevent double-crediting. Update internal transaction status, invoices, and receivables to 'Failed', 'Voided', or ‘Unpaid’ to align with the void event.

Digital Wallets

Digital Wallet testing requires a live gateway configuration. You must add valid credit or debit cards to your Apple or Google Wallet before testing.

Success Scenarios

Complete the transaction using your device's digital wallet at checkout.

Failure Scenarios

To simulate declines, test with an invalid card or a gift card with a $0 balance.

If your account is set up for Digital Wallets, you can learn more in Accepting Apple or Google Pay.

Legacy Sandbox Accounts

If any of the card numbers listed in this article are not working as documented, you may be using a legacy sandbox account. Please reach out to support to request to be upgraded to the new sandbox account for full testing functionality.