Test Stripe Terminal

Learn how to effectively test your Terminal integration.

Note

Much of the process for testing Stripe Terminal is similar to that for testing online Stripe payments. Also, you can’t use Stripe Terminal with mobile wallets (for example, Apple Pay or Google Pay) in testmode. For more information, see the general Stripe testing guide.

The best way to achieve a successful Terminal deployment is to test every part of your integration. We provide testing tools for each stage:

1. Before ordering a reader, test your integration with the reader simulator.
2. Test your complete hardware integration with a physical test card.

Simulated reader

Stripe Terminal SDKs and server-driven integration come with a built-in simulated card reader, so you can develop and test your app without connecting to physical hardware. Whether your integration is complete or you’re still building it, use the simulated reader to emulate all the Terminal flows in your app.

The simulated reader doesn’t provide a UI. After connecting to it in your app, you can see it working when calls to the Stripe SDK or API succeed.

Simulated readers for SDKs automatically simulate card presentment as needed. For the server-driven integration, update your integration to simulate card presentment.

Simulated test cards

The simulated reader can be configured to use a simulated test card, enabling you to test different flows within your point of sale application.

Before collecting a payment method, configure the simulated reader to use one of the following test card numbers or test payment methods to produce specific responses. Configuration set during the collect step (such as the test card number) is persisted for 30 minutes. This means a subsequent confirm step uses the same configuration, even if you don’t pass it again explicitly. Any configuration passed on the confirm call takes priority over the cached values from the collect step.

Standard test cards

Test cards for specific success cases

Test cards for specific error cases

Note

Using these specific cards for saving directly without charging and SetupIntents returns a setup_intent_authentication_failure response.

Simulated card presentment

When using the server-driven integration, use the present_payment_method endpoint to simulate a cardholder tapping or inserting their card on the reader.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

{
 "id": "tmr_xxx",
 "object": "terminal.reader",
 "action": {
 "failure_code": null,
 "failure_message": null,
 "process_payment_intent": {
 "payment_intent": "pi_xxx"
 },
 "status": "succeeded",
 "type": "process_payment_intent"
 },
 …
}

If you don’t specify parameters, the simulated payment defaults to a valid test card based on the payment method type of the PaymentIntent. Below are the default test cards for Terminal payment method types:

With the standard test cards, you can also use test amounts to simulate failure scenarios

Test reader update

Use reader software update scenarios to test how your integration handles updates. This works with simulated and physical mobile readers in a sandbox.

Set the testReaderUpdate property on BluetoothConnectionConfiguration, UsbConnectionConfiguration, or TapToPayConnectionConfiguration to trigger a reader update scenario during connection. This works with simulated and physical mobile readers, and with simulated Tap to Pay readers in a sandbox.

Create a TestReaderUpdate with one of the factory methods. You can optionally specify UpdateComponent values such as .firmware, .config, .keys, or .incremental.

ConnectReaderViewController.swift

Select a language

Swift

Objective-C

No results

// Create a TestReaderUpdate to simulate a required update during connection
let testReaderUpdate = TestReaderUpdate.required([.firmware, .config])

let connectionConfig: BluetoothConnectionConfiguration
do {
 connectionConfig = try BluetoothConnectionConfigurationBuilder(delegate: readerDelegate, locationId: "{{LOCATION_ID}}")
 .setTestReaderUpdate(testReaderUpdate)
 .build()
} catch {
 // Handle the error building the connection configuration
 return
}
Terminal.shared.connectReader(selectedReader, connectionConfig: connectionConfig) { reader, error in
 if let reader = reader {
 print("Successfully connected to reader: \(reader)")
 } else if let error = error {
 print("connectReader failed: \(error)")
 }
}

Note

TapToPayConnectionConfiguration only supports the .required(components) scenario. Other types return an error.

Use the SimulatorConfiguration approach Deprecated

Caution

The simulatorConfiguration.availableReaderUpdate approach is deprecated as of SDK 5.5. Use the testReaderUpdate connection configuration property instead.

Set Terminal.shared.simulatorConfiguration.availableReaderUpdate to one of the following configurations. Calling connectReader triggers a simulated reader update. This only works with the simulated mobile reader.

Physical test cards

Test payments with your Stripe Terminal reader using a physical test card. You can purchase readers and physical test cards from the Terminal tab in the Stripe Dashboard. We also support physical test cards from providers, such as B2.

This physical test card supports both chip entry and contactless payments. It only works with Stripe’s pre-certified readers, and only against the Stripe API in a sandbox. If you attempt to use your physical test card in live mode, the Stripe API returns an error. Unless stated otherwise, use the PIN 1234 when prompted.

When creating payments using a physical test card, use amounts ending in the following decimal values to produce specific responses:

For example, a payment processed using a physical test card for the amount _25.00 the related setting succeeds; a payment processed for the amount _10.05 the related setting is declined.

Note

Some currencies have zero decimal. For those currencies, use the two decimal digits in the table above as the rightmost two digits.

For example, to get your payment declined with generic_decline code, you need an amount of _105 the related setting.

Interac test cards Canada only

To test your Interac integration, you can use the simulated interac test card or an Interac physical test card. You can order it from the Terminal hardware shop in the Dashboard. You can’t use the Stripe-branded physical test card as an Interac card.

The Interac test card works for both interac_present payments and interac_present refunds. You can use the same test amounts you use for testing card_present payments. Unless stated otherwise, use the PIN 1234 when prompted. To test a declined refund, create a partial refund with an amount ending with the following decimal values: 01, 05, 55, 65, or 75.

Note

The Interac test card doesn’t support contactless payments.

eftpos test cards Australia only

To test your eftpos integration, you can use the simulated eftpos test card or an eftpos physical test card. You can order it from the Terminal hardware shop in the Dashboard. You can’t use the Stripe-branded physical test card as an eftpos card.

You can use the same test amounts you use for testing card_present payments. Unless stated otherwise, use the PIN 1234 when prompted.

See also

• Place orders
• Integration checklist
• Test additional payment methods