Guides

Setup and Testing

Suggest Edits

Overview

For development and testing, developers should use test.bitpay.com, a relative copy of BitPay's production site running on testnet.

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 (see Getting Access). Finally, a testnet compatible wallet must be used to make test payments.

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

Read Before You Test

When testing on BitPay's testnet, there are several things that developers should keep in mind to ensure they are testing effectively and efficiently.

First, it's important to note that not all wallets, currencies, or features are supported on BitPay's testnet environment. Therefore, when testing, it's recommended to use BitPay's wallet product or the MetaMask wallet for testnet Bitcoin and Ethereum transactions respectively. Additionally, it's important to be aware of the testnet environment limitations and to use it solely for testing purposes, rather than for real transactions and certainly not for verifying BitPay's User Experience. NOTE - BitPay's test environment allows you to simulate payments rather than utilizing testnet blockchains/currencies. See the Mock Payment section below for details.

While the testnet environment provides a way to simulate the payment processing flow, it does not always accurately reflect the real-world customer experience. For example, testers may encounter user experience errors or issues when attempting to pay an invoice on the testnet environment. Please note these are merely a factor of the test environment and are not representative of production.

By keeping these factors in mind, developers can ensure that they are testing effectively and efficiently on BitPay's testnet environment.

What Should You Test

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 types of transaction:

  • A fully paid invoice, paid on time (within 15 minutes of invoice generation)
  • A fully paid invoice, paid after invoice expiration (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.
  • Refunding an invoice partially and fully
  • Listening for and interacting with Instant Payment Notifications (webhooks).

Other testing scenarios will depend on your specific needs and it is advised your test each feature of your application before moving to production.

Lastly, load testing our API is not advised or necessary and your application may be rate limited if load tests are detected.

Merchant/Developer 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. Fake settlement/bank information will be prefilled so you don't have to enter anything.
  2. Pair your client with your BitPay merchant account. If you are using one of BitPay's plugins or code libraries, detailed steps are described in the corresponding documentation.

Mock Payment Functionality

BitPay's test environment supports payments on several testnet blockchains, which will allow you to approximate the production payment experience. However, testnet blockchains can often present challenges to users, such as high fees and low public supplies of coins. To provide an alternative option for users of our test environment, we support the ability to "mock pay" an invoice. A mock payment will automatically move the payment into a completed status, allowing you to bypass the testnet.

To mock pay an invoice:

  • Using our API - see API documentation here. After creating an invoice, send a PUT with the status field updated. Note, when creating the invoice, you need to include "buyerProvidedInfo" for "selectedWallet" and "selectedTransactionCurrency" (example values are "bitpay" and "BTC" respectively).
  • Using the UI - work through the payment experience as you would for a real payment. After selecting a wallet and currency (you will need to select a wallet that allows for currency selection on the web UI, such as Trust Wallet) you will reach the payment page with a QR code. At the bottom of the page, click the "Simulate Payment" button to mark the payment completed.

Getting a Testnet Bitcoin Wallet

Not every wallet has 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. Follow this guide to create a testnet wallet. Steps may vary slightly depending on your device. Summarized instructions here:
    1. Once you have created your first standard wallet in the app, select My Key >Add Wallet > Basic Wallet > Bitcoin > Show Advanced Options > then check only Testnet
    2. On the next screen, under the Advanced Options enable the testnet option.
    3. Click on the Create button.

Nice work! Your wallet is active and is now ready to load up with Testnet Bitcoin.

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:

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

Recycle Your Test Bitcoin

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.

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 or download to your Android or Apple device.
  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 "Sepolia Test Network".

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 Sepolia Testnet and paste your testnet wallet address into the request form provided. We recommend the following testnet faucet:

Updated 2 days ago