Testing

For development and testing, BitPay users can access test.bitpay.com, a mirror of our production site running on the the Bitcoin Testnet.

Developers must complete the normal signup process, but accounts on this server will be auto-approved to process up to $1,000 per day and $10,000 annually in test transactions. To process a greater volume in test transactions, please email our team requesting a tier upgrade.

Before you begin testing, note that any API requests must be directed to test.bitpay.com, and any clients must complete the client pairing process against this server as well. Finally, a testnet-compatible wallet must be used to make test payments.

Below are some helpful pointers for getting started with test.bitpay.com:

Merchant Account Setup

Complete the following steps to setup your merchant account for testing:

  1. Sign up for a BitPay testnet account.

  2. Pair your client against the server at test.bitpay.com by following the client pairing process provided by your sales engineer or detailed in the setup guide for your BitPay plugin or integration.

Getting a Testnet Wallet

Not every wallet supports the Bitcoin testnet. We recommend testing with our open source wallet BitPay, but any testnet-compatible wallet can be used.

  1. Visit bitpay.com/wallet and download the wallet for your chosen laptop or desktop OS, mobile platform, or browser.

  2. Once you have created your first standard wallet in the app, select the + icon on your wallet's home screen. Select "Create New Wallet," verify that "Personal Wallet" is selected, and provide a name for your testnet wallet.

  3. Select "Advanced Options" and activate the "Testnet" option provided.

  4. Click on "Create new wallet" and verify that "Testnet" is displayed below the wallet name.

  5. Select the app's gear icon to open the app's settings, then scroll to “Global Settings” and change "Bitcoin Unit" to "BTC" to match BitPay invoices.

  6. Nice work! Your wallet is active and is now ready for testing.

Getting Testnet Coins

  1. Open your BitPay wallet and click on the "Receive" tab. Scroll through your wallets to find your testnet wallet. You'll see an address at which you can receive funds. Copy this address to your clipboard.

  2. Find a testnet faucet and paste your testnet wallet address into the request form provided. We recommend the following testnet faucets:

  3. Select the send option for the testnet faucet, then return to your wallet to see the newly deposited test funds!

Round Trip Testing

In order to recycle your test coins, set your test.bitpay.com settlement address to your testnet wallet's receiving address (note: most testnet bitcoin addresses begin with the prefix m or n rather than the prefix 1 or 3 of mainnet bitcoin addresses) and set payment at 100% BTC.

Setting up your merchant account this way allows the bitcoin you send for payment to be circulated back to you when merchant payouts are run.

Testing Considerations

Testing may involve not only the integration of the BitPay service and the payment of invoices but also how you handle common payment exceptions.

You should consider testing the following kinds of transactions:

  • A fully paid invoice, paid on time (within 15 minutes of invoice generation)

  • A fully paid invoice, paid late (after 1 hour, after 24 hours)

  • An underpaid invoice (pay an amount less than the invoice requires.)

  • An overpaid invoice (pay an amount more than the invoice requires.)

  • An invoice with and without wallet fees:

    • Try to force an invalid transaction using a low value invoice with no wallet fees. Invalid transactions are invoices that have been paid but which have zero confirmations within one hour of being received by the BitPay server.