WooPayments: Sandbox Mode

NOTE: Sandbox mode was called dev mode prior to version 7.1.0 of WooPayments. We changed this name to better clarify its intended purpose, but the functionality remains the same.

If you want to test WooPayments on a site that will not need to process real payments, you can use sandbox mode.

With sandbox mode, it’s possible to create a test account that requires no personal information. This account can then be used to process test transactions. It will only operate in test mode and cannot be used to run real charges.

NOTE: WooPayments must be connected to WordPress.com — even in sandbox mode. This means it’s not possible to run WooPayments locally unless you expose your site to the Internet with ngrok or a similar tool.

Enabling sandbox mode

↑ Back to top

To enable sandbox mode, you can select the Enable sandbox mode option when signing up for WooPayments:

However, sandbox mode can also be enabled by either:

  • Setting your site’s environment type to either development or staging.
  • Adding the following constant to your site’s wp-config.php file:
define( 'WCPAY_DEV_MODE', true );

In these instances, you will see a notice during the sign up process that indicates that Sandbox mode is enabled and that only test accounts will be created — no matter which option is selected during the signup process.

NOTE: Using the same site for testing in sandbox mode and later accepting live payments could lead to confusion. For example, transactions performed with a sandbox mode account will still be visible under WooCommerce > Orders — but not under Payments > Transactions — once a live account is used.

It is best to only use sandbox mode on staging URLs which will never need to take real transactions.

Create a test account

↑ Back to top

Once you’ve enabled sandbox mode, you will need to create a test account.

You can complete the test account creation process using the following steps:

  1. In your site’s dashboard, click the Payments menu item.
  2. Click the Finish Setup button.
  3. Connect to your WordPress.com account by entering your credentials and approving the connection.
  4. Select the I’m building a store for someone else and would like to test payments option.
  5. Select the Continue button.
  6. From here, the setup process will continue on Stripe’s site, hosted at connect.stripe.com.
    • You can verify that a test account is being created by looking for the “Test Mode” box toward the top of the page:
  1. For the phone number:
    • Choose any country.
    • Enter all zeroes.
  2. Stripe will ask you to verify the phone number.
    • Click the Use test code button.
  3. Enter your preferred country and type of business.
  4. Enter any name and birthdate that’s in the past.
  5. Enter any valid email address.
  6. Enter any valid physical address.
  7. Enter all zeros for requested identification information.
  8. Enter any industry.
  9. For your payout account details, select one of the following options:
    • The Bank account option and choose either:
      • One of the test deposit account cards.
      • The Enter test bank account credentials instead link, then click the Use test account button to populate test bank details.
    • The Debit card option, then click the Use test card button to populate test debit card information.
  10. At the end, click Agree and submit to create the test account.
  11. You will be redirected back to the Payments > Overview section of your site’s administrator dashboard.

Once you are back at your site, you can verify that you’re in sandbox mode via the notice at the top of the Payments > Overview page or the notice under Payments > Settings:

Disabling sandbox mode

↑ Back to top

Disabling sandbox mode allows you to set up a live WooPayments account that can accept real payments.

To disable sandbox mode, select the Set up payments button on either the Payments > Overview page or in the WooPayments settings page at Payments > Settings.

Once sandbox mode is disabled, you can sign up for a live WooPayments account using real personal and business information.

NOTE: If you’ve enabled sandbox mode by adding a constant or changing your site’s environment type, sandbox mode will still be enabled after selecting the Set up payments option.