Testing & troubleshooting

Testing integrations with a remote service like Spreedly can be tricky, with the added complexity that Spreedly itself acts as a proxy to other remote services. This guide attempts to answer such questions and to provide a clear process for testing transactions in a Spreedly environment.


On account creation, Spreedly provisions a unique organization and one environment. To be ready to test in Spreedly, a test gateway and payment are also required.

Test environments

Spreedly does not have a distinct "test environment" type. It is recommended to create and keep at least one environment dedicated to testing only, using test/sandbox gateways and running test transactions. However, adding a production connection to an environment will enable that connection, allowing for production transactions in any environment. Keep this in mind during environment setup - all environments are created equal and will allow billable transactions.

Test gateway and payment methods

The Spreedly Test gateway acts and behaves just like a production gateway and supports both direct and offsite gateway functionality as well as 3D Secure and bank accounts. Creating a test gateway will allow testing of all possible payment flows. A test gateway prevents transactions with live data, thus only test payment methods to work with the gateway. (The same is true of the test receiver type).

To create a test payment method, use the standard payment method collection process specifying a test credit card or bank account number instead of a real number. These will automatically be recognized as test payment methods by Spreedly and will be allowed to transact against the test gateway.

Spreedly offers a test payment method type, called Sprel. It is only recognized by our test gateway, and is especially useful in building Offsite Payments workflows.

Once you have the integration working with test data, it should work seamlessly with production gateways and real payment types. Issues with production gateways or receivers can often be located by reviewing transcripts of the transaction(s) in question.

It’s important to note that test API calls are metered and billed for Spreedly customers. Any threshold management or alerting must be handled programmatically by the customer.

Testing new changes

Spreedly releases changes to our products, APIs, and various gateway integrations on a frequent basis. Keeping up with these changes is important to ensure tests continue passing, and to cover new test cases made available with updates to functionality. Any change with potential impact can be found on our Changelog. Alternatively, you can subscribe to the Changelog RSS feed here. An archive of past changes and Changelog updates is available on our legacy documentation site.

Gateway sandboxes

Once confident that your payment flows are configured correctly against the test gateway, the goal is to then create your first Production environment and repeat the process with Production gateways for testing.

Production gateways can be created in sandbox mode. Using sandbox mode on a production gateway can help uncover integration issues in complex scenarios by processing simulated card data and transactions in the authenticated environment. Sandbox mode is only recommended in situations where the gateway integration is difficult. It is not for production transactions. Please be aware that a gateway sandbox account may behave quite differently from the real production account.

Spreedly strongly recommends using a separate environment and gateway token only for sandbox testing.

Note: On production accounts, API calls to gateways in sandbox mode are billable.

Unit tests with Spreedly

The process of running tests can lead to further questions. Do you invoke real API calls within your tests which can greatly reduce their speed of execution? Do you mock out the remote service, which involves some development work and reduces efficacy of the tests?

Users should take a hybrid approach, from the ActiveMerchant library to which we contribute:

  • Maintain a set of unit tests that mock out the main Spreedly API endpoints you’re using. These tests execute very quickly and provide good peace of mind that no regressions have occurred with each incremental change to your code base.
  • Also maintain a set of “remote” unit tests that hit the Spreedly API (using test data). These tests will execute much slower, so the expectation is not that they run on every code change. Run them on major milestones to ensure continued compatibility, or run a subset of them to verify that the modified portions of your system are still operating as expected.

Load testing

For production environments, gateway processing makes up most of the time spent waiting for transactions to complete (in other words, you’re not waiting on Spreedly). Spreedly's test gateway offers nearly instantaneous responses which are not representative of transacting against an actual gateway. With no “real-world” delay, the accuracy of this load test is diminished.

One suggested workaround to consider: with unit tests, it might help to simply mock out Spreedly calls with an expected delay from a given gateway (perhaps 2-5 seconds).

We understand that testing high loads before releasing a new feature or going into production is an important process for some organizations. However, it is crucial to remember that Spreedly reserves the right to throttle or prohibit testing that we deem to be excessive. We want to keep our core services up and running for everyone, and will prioritize production transactions over tests. If you’re planning on performing high amounts of load testing through our test gateway, please contact Support to start the conversation.