Testing

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

Developers must complete the normal signup process, but accounts on this server will be auto-approved.

Before you begin testing, note that any API requests must be directed to test.bitpay.com as base API url, 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. Make sure to verify your email and fill in your business information & settlement information. See “Settlement Testing” below for what information to enter.

2. Pair your client with your BitPay merchant account. If you are using one of your BitPay’s plugin or code library, detailed steps are described in the corresponding documentation.

Getting a Testnet Bitcoin Wallet

Not every wallet have testnet support for most of the currencies available on the BitPay platform. 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, click on the + icon on the wallet’s home screen, then select the Simple Wallet option followed by the currency for the wallet.

3. On the next screen, under the Advanced Options enable the testnet option.

4. Click on the Create button.

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

Getting a Testnet ETH Wallet

If you are testing ETH payments, we recommend the MetaMask wallet.

1. Add the MetaMask wallet extension to your Chrome browser.

2. Follow the instructions to create and back up a wallet. Your wallet will automatically be set to use the main Ethereum network.

3. Click the dropdown network selector in the upper right-hand corner of your wallet’s screen to select “Goerli Test Network”.

Getting Testnet Bitcoin

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:

   • testnet-faucet.mempool.co

   • bitcoinfaucet.uo1.net/

   • kuttler.eu/en/bitcoin/btc/faucet/

   • testnet.coinfaucet.eu

   • If the faucets are unavailable or temporarily out of testnet coins, please contact our support team.

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

Getting Testnet ETH

1. Open your MetaMask wallet and click on the “Deposit” button.

2. Copy the address string shown beneath the QR code. This is your testnet wallet address.

3. Find a testnet faucet for the Goerli Testnet and paste your testnet wallet address into the request form provided. We recommend the following testnet faucet:

   • fauceth.komputing.org/?chain=5

   • If this option is unavailable, please contact our support team.

Once you submit your address to the testnet faucet, you should receive ETH testnet funds shortly.

Settlement Testing (BTC Only)

In order to recycle your Bitcoin testnet 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.