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.
| BRAND | NUMBER | CVC | DATE |
|---|---|---|---|
| Visa | 4242424242424242 | Any 3 digits | Any future date |
| Visa | 4000056655665556 | Any 3 digits | Any future date |
| Mastercard | 5555555555554444 | Any 3 digits | Any future date |
| Mastercard | 2223003122003222 | Any 3 digits | Any future date |
| Mastercard | 5200828282828210 | Any 3 digits | Any future date |
| Mastercard | 5105105105105100 | Any 3 digits | Any future date |
| American Express | 378282246310005 | Any 3 digits | Any future date |
| American Express | 371449635398431 | Any 3 digits | Any future date |
| Discover | 6011111111111117 | Any 3 digits | Any future date |
| Discover | 6011000990139424 | Any 3 digits | Any future date |
| Discover | 6011981111111113 | Any 3 digits | Any 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.
| BRAND | NUMBER | ERROR CODE |
|---|---|---|
| Visa | 4726842594400889 | card_declined |
| Visa | 4726840306461785 | expired_card |
| Visa | 4726840756845529 | incorrect_cvc |
| Visa | 4726849921107855 | processing_error |
| Visa | 4726843991344803 | incorrect_number |
| Visa | 4726846912498186 | insufficient_funds |
| Visa | 4726843338079575 | stolen_card |
| Visa | 4726848138487043 | generic_decline |
| Visa | 4726848912206759 | card_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 NUMBER | ROUTING NUMBER | BEHAVIOR |
|---|---|---|
000123456789 | 110000000 | Payment succeeds |
000111111113 | 110000000 | Payment fails - Account closed |
000111111116 | 110000000 | Payment fails - Account not found |
000222222227 | 110000000 | Payment fails - Insufficient funds |
000333333335 | 110000000 | Payment fails - Debits not authorized |