Testing

To ensure your integration functions correctly, use our test mode to simulate transactions without moving real money. This section covers how to use special test values for various payment scenarios.

Test cards allow you to simulate different payment outcomes:

  • Successful payments by card brand
  • Card errors due to declines, fraud, or invalid data

Because of rate limits, we don't recommend using test mode to load-test your integration. Instead, see our documentation on load testing.

How to use test cards

Any time you work with a test card, use test API keys in all API calls. This is true whether you're serving a payment form to test interactively or writing test code.

Warning

Never use real card details for testing. The Frame Services Agreement prohibits testing in live mode with actual payment method information. Stick to test API keys and the provided test card numbers.

Test code

Currently, we only support using card numbers directly in API calls. Don't worry about PCI compliance during testing - your code will be compliant when live because your data will be encrypted and we never have access to the actual card details. By default, a PaymentMethod isn't attached to a Customer. You'll need to handle this association if required for your use case.

When you're ready to process real payments, replace your test publishable and secret API keys with live ones.

Cards by brand

To simulate a successful payment, use test cards from the following list.

BRANDNUMBERCVCDATE
Visa4242424242424242Any 3 digitsAny future date
Visa4000056655665556Any 3 digitsAny future date
Mastercard5555555555554444Any 3 digitsAny future date
Mastercard2223003122003222Any 3 digitsAny future date
Mastercard5200828282828210Any 3 digitsAny future date
Mastercard5105105105105100Any 3 digitsAny future date
American Express378282246310005Any 3 digitsAny future date
American Express371449635398431Any 3 digitsAny future date
Discover6011111111111117Any 3 digitsAny future date
Discover6011000990139424Any 3 digitsAny future date
Discover6011981111111113Any 3 digitsAny future date

Declined payments

To test your integration's error-handling logic, use the following test cards to simulate payments that issuers decline for various reasons. Using these cards results in a card error with the specified error code.

BRANDNUMBERERROR CODE
Visa4726842594400889card_declined
Visa4726840306461785expired_card
Visa4726840756845529incorrect_cvc
Visa4726849921107855processing_error
Visa4726843991344803incorrect_number
Visa4726846912498186insufficient_funds
Visa4726843338079575stolen_card
Visa4726848138487043generic_decline
Visa4726848912206759card_velocity_exceeded

Rate limits

If your requests in test mode start receiving 429 HTTP errors, reduce the frequency of your requests. These errors are from our rate limiter, which is more restrictive in test mode compared to live mode.

Important notes on rate limits:

  • We don't recommend load testing your integration using the Frame API in test mode.
  • The rate limiter is stricter in test mode, so you might encounter errors that wouldn't occur in production.
  • For load testing, refer to our dedicated load testing documentation for alternative approaches.

Non-card payments

When testing non-card payment methods, always use test API keys for all API requests, regardless of whether you're testing an interactive payment form or writing automated test code.

ACH test account numbers

Use these pre-configured test account numbers to validate your integration for manually-entered bank accounts before going to production.

ACCOUNT NUMBERROUTING NUMBERBEHAVIOR
000123456789110000000Payment succeeds
000111111113110000000Payment fails - Account closed
000111111116110000000Payment fails - Account not found
000222222227110000000Payment fails - Insufficient funds
000333333335110000000Payment fails - Debits not authorized