Testing Scenarios Guide

This guide covers how to test Flute payment integrations using the sandbox, including test cards, ACH accounts, error conditions, and load testing.

The Flute sandbox is a fully isolated environment that mirrors production behavior without processing real transactions. Use it to validate your integration before going live.

Before running tests, ensure you have:

1. A sandbox merchant account provided by Flute. See Creating a Flute Sandbox Account.
2. A sandbox API key that includes the clientId and client secret. See Creating an API Key.
3. An API token generated from your sandbox environment credentials. See API Tokens.

The sandbox supports two simulation modes depending on how the card is presented.

Card Not Present (CNP): The result is determined by the card number submitted. Use the test PANs listed in the tables below.

Card Present (CP): Because the PAN rides inside track or EMV data that the sandbox does not parse, the result is determined by the transaction amount instead. Use any card and set the amount to one of the values in the tables below. Applies to Swipe, EMV, NFC, EMVContactless, and FallbackSwipe data sources. Manual keyed entry is treated as CNP.

For CNP, any card number not listed in the Decline or Processor Error tables is approved. For CP, any amount not listed in those tables is approved.

• Expiration date: Any future date (e.g. 12/34)
• CVV: Any 3- or 4-digit numeric value (e.g. 123)

Use the CNP card number or the CP amount to trigger a specific issuer decline.

Use the CNP card number or the CP amount to trigger a specific processor error.

The sandbox can simulate a partial approval, where the issuer approves only a portion of the requested amount. This scenario is only available for CP transactions.

Use the following PAN to replicate a Level 3 commercial card.

Use any of these addresses to replicate an AVS (address verification system) check.

The sandbox decides the AVS result from the billing street and zip on the request. The AVS check itself always succeeds.

To simulate a full AVS match, use:

• Street: 123 Test St
• Postal code: 10001

All street and postal code combinations are covered in the table below.

AVS Profile and Transaction Outcome. The AVS result alone does not determine whether a transaction is approved or declined. The final outcome also depends on the merchant's AVS Profile, configured in the merchant dashboard settings.

ACH (Automated Clearing House) is the network used to process bank account payments, including direct debits and credits between bank accounts. The sandbox supports full ACH testing, including specific return codes, lifecycle status transitions, and edge cases such as holds and chargebacks.

Use the bank routing and account number combinations below to simulate specific outcomes. Each combination maps to a predefined response, allowing you to validate error handling, status transitions, and business logic.

The following operations can be tested:

• Verify account (positive, negative, or error)
• Payment (debit or credit)
• Refund a cleared payment
• Void a payment before submission
• Hold a scheduled payment and release it
• Lifecycle status transitions

Real-world ACH processing is asynchronous and takes up to three business days to clear, updating statuses up to four times a day. To help with testing, sandbox lifecycle status changes are shortened.

The ACH sandbox triggers status changes automatically every 15 minutes. This compresses the end-to-end testing window to approximately one hour.

A typical approved payment progresses through: Scheduled → In Progress → Cleared

A declined payment progresses through: Scheduled → Declined

Use the following routing and account number to simulate a successful ACH transaction. Any routing and account number combination not listed in the Decline Scenarios table below is also approved.

The sandbox triggers ACH return codes when the routing and account number pairings match from the list below.

"Soft returns" describe the state of the transaction, not the account. For example, Verify Account still reports the account as usable, but an actual payment with the same routing and account values is declined with the appropriate R-code.

Once an ACH payment is approved, the routing and account numbers also decide the path it will take through its lifecycle.

Hold, Remove Hold, Void, and Refund only apply in the correct state. If you attempt them at the wrong moment, the sandbox declines with an explanatory message.

• Void requires status Scheduled
• Hold requires status Scheduled
• Remove Hold requires status Held
• Refund requires the parent transaction to be Cleared

Test each error type to ensure your integration handles failures gracefully and communicates clearly with end users.

Duplicate controls is a configurable feature that prevents duplicate transactions from being processed, reducing the risk of double-charging customers. It is available at the merchant account level and can be enabled and customized in the merchant dashboard.

When enabled, each incoming payment transaction is compared against recent transactions from the same merchant. If a match is found within the validation period, the transaction is flagged as a duplicate and rejected.

A duplicate transaction returns HTTP 400 with a V0000 validation error (ValidationException).

A transaction is considered a duplicate if all the following fields match:

• Operator ID (API client ID, terminal ID, or user ID)
• Merchant ID
• Amount
• Operation type (Auth or Sale)
• Card number (last four digits)
• Reference ID (if provided)

The duplicate check applies within a configurable validation period (default: 10 minutes).

If the new transaction is legitimate, you can either:

• Wait for the validation period to expire and resubmit, or
• Set a different reference ID and resend immediately.

Focus your load tests on the endpoints your integration uses most heavily. For each endpoint, measure: