Guides

Creating Invoices

Suggest Edits

An invoice is created by sending an HTTP POST message to bitpay.com/invoices with the details of the invoice passed in the body of the request.

The body of the request must be JSON encoded and the request shall have the following HTTP headers:

  • content-type must be set to application/json
  • x-accept-version must be set to 2.0.0

On successful creation, the invoice details will be provided in a JSON encoded response.

If there is an error, you will receive a JSON encoded error response. All error responses will have an error field that is an object with two fields called type and message. A merchant is restricted to creating no more than 100 invoices per hour (there are also per second and per minute limits). The fields in the request are described below.

Required POST Fields

price

This is the amount that is required to be collected from the buyer. Note, if this is specified in a currency other than BTC, the price will be converted into BTC at market exchange rates to determine the amount collected from the buyer.

currency

This is the currency code set for the price setting. Supported pricing currencies include USD, EUR, BTC, and all currencies listed on our BitPay Exchange Rates page.

token

The API token can be retrieved from the BitPay Dashboard or using the Tokens resource via the REST API (see the full API reference - Request an API token).

Optional Payment Notification (IPN) Fields

The BitPay invoice service can be configured to send JSON-encoded POST callbacks to a merchant-provided URL endpoint. Settings for this capability are described below.

posData

A passthru variable provided by the merchant and designed to be used by the merchant to correlate the invoice with an order or other object in their system. This passthru variable can be a serialized object, e.g.:

posData: '{ "ref" : 711454, "affiliate" : "spring112" }'

notificationURL

URL to which BitPay sends webhook notifications, HTTPS is mandatory. BitPay sends IPN callback to this URL when the invoice status changes.

transactionSpeed

This is a risk mitigation parameter for the merchant to configure how they want to fulfill orders depending on the number of block confirmations for the transaction made by the consumer on the selected cryptocurrency (BTC, BCH, ETH, XRP, etc). For instance, with a invoice paid in Bitcoin (BTC):

high
An invoice is considered to be confirmed immediately upon receipt of payment.

medium
An invoice is considered to be confirmed after 1 block confirmation (~10 minutes).

low
An invoice is considered to be confirmed after 6 block confirmations (~1 hour).

Note:

  • If not set on the invoice, transactionSpeed will default to your account-level order settings.
  • orders are always posted to your BitPay Account Summary for settlement after 6 block confirmations (regardless of this setting).

Optional Order Handling Fields

redirectURL

The shopper will be redirected to this URL when clicking on the Return button after a successful payment or when clicking on the Close button if a separate closeURL is not specified. Be sure to include "http\://" or "https\://" in the url.

closeURL

URL to redirect if the shopper does not pay the invoice and click on the Close button instead. Be sure to include "http\://" or "https\://" in the url.

autoRedirect

Set to false by default, merchant can setup automatic redirect to their website by setting this parameter to true. This will applied to the following scenarios:

When the invoice is paid, it automatically redirects the shopper to the redirectURL indicated
When the invoice expires, it automatically redirects the shopper to the closeURL if specified and to the redirectURL otherwise

Note: if automatic redirect is enabled, redirectURL becomes a mandatory invoice parameters.

Optional Display Information

orderId

Can be used by the merchant to assign their own internal ID to an invoice. If used, there should be a direct match between an orderId and an invoiceId.

itemDesc

Invoice description - will be added as a line item on the BitPay checkout page, under the merchant name.

Buyer object

The buyer object can be used by the merchant to pass customer information on the BitPay invoice. The following parameters are available for this JSON object:

  • name
  • address1
  • address2
  • locality
  • region
  • postalCode
  • country
  • email
  • phone

BitPay Server Response

{
  "facade": "merchant/invoice",
  "data": {
     "url": "https://bitpay.com/invoice?id=G3viJEJgE8Jk2oekSdgT2A",
     "status": "new",
     "price": 10,
     "currency": "USD",
     "orderId": "20210511_fghij",
     "invoiceTime": 1620733980748,
     "expirationTime": 1620734880748,
     "currentTime": 1620733980807,
     "id": "G3viJEJgE8Jk2oekSdgT2A",
     "lowFeeDetected": false,
     "amountPaid": 0,
     "displayAmountPaid": "0",
     "exceptionStatus": false,
     "targetConfirmations": 6,
     "transactions": [],
     "transactionSpeed": "medium",
     "buyer": {
        "email": "[email protected]"
     },
     "redirectURL": "https://merchantwebsite.com/shop/return",
     "closeURL": "https://merchantwebsite.com/shop/cancel",
     "refundAddresses": [],
     "refundAddressRequestPending": false,
     "buyerProvidedEmail": "[email protected]",
     "buyerProvidedInfo": {
        "emailAddress": "[email protected]"
     },
     "paymentSubtotals": {
        "BTC": 18000,
        "BCH": 739100,
        "ETH": 2505000000000000,
        "GUSD": 1000,
        "PAX": 10000000000000000000,
        "BUSD": 10000000000000000000,
        "USDC": 10000000,
        "XRP": 7015685,
        "DOGE": 1998865000,
        "DAI": 9990000000000000000,
        "WBTC": 18000
     },
     "paymentTotals": {
        "BTC": 29600,
        "BCH": 739100,
        "ETH": 2505000000000000,
        "GUSD": 1000,
        "PAX": 10000000000000000000,
        "BUSD": 10000000000000000000,
        "USDC": 10000000,
        "XRP": 7015685,
        "DOGE": 1998865000,
        "DAI": 9990000000000000000,
        "WBTC": 18000
     },
     "paymentDisplayTotals": {
        "BTC": "0.000296",
        "BCH": "0.007391",
        "ETH": "0.002505",
        "GUSD": "10.00",
        "PAX": "10.00",
        "BUSD": "10.00",
        "USDC": "10.00",
        "XRP": "7.015685",
        "DOGE": "19.988650",
        "DAI": "9.99",
        "WBTC": "0.000180"
     },
     "paymentDisplaySubTotals": {
        "BTC": "0.000180",
        "BCH": "0.007391",
        "ETH": "0.002505",
        "GUSD": "10.00",
        "PAX": "10.00",
        "BUSD": "10.00",
        "USDC": "10.00",
        "XRP": "7.015685",
        "DOGE": "19.988650",
        "DAI": "9.99",
        "WBTC": "0.000180"
     },
     "exchangeRates": {
        "BTC": {
          "USD": 55413.609335,
          "EUR": 45540.39841,
          "BCH": 40.84109737914668,
          "ETH": 13.870219975470258,
          "GUSD": 55413.609335,
          "PAX": 55413.609335,
          "BUSD": 55413.609335,
          "USDC": 55413.609335,
          "XRP": 38758.09372049268,
          "DOGE": 110606.00665668662,
          "DAI": 55359.96552840298,
          "WBTC": 0.9981333606461704
        },
        "BCH": {
          "USD": 1352.90925,
          "EUR": 1111.2150000000001,
          "BTC": 0.02440102556111244,
          "ETH": 0.33863791096704754,
          "GUSD": 1352.90925,
          "PAX": 1352.90925,
          "BUSD": 1352.90925,
          "USDC": 1352.90925,
          "XRP": 946.2690507998013,
          "DOGE": 2700.4176646706587,
          "DAI": 1351.599550036015,
          "WBTC": 0.024369173431532262
        },
        "ETH": {
          "USD": 3992.672665000001,
          "EUR": 3278.9696950000002,
          "BTC": 0.0720117094001833,
          "BCH": 2.9426910658087726,
          "GUSD": 3992.672665000001,
          "PAX": 3992.672665000001,
          "BUSD": 3992.672665000001,
          "USDC": 3992.672665000001,
          "XRP": 2792.6060619837313,
          "DOGE": 7969.406516966069,
          "DAI": 3988.807510522304,
          "WBTC": 0.07191770817497412
        },
        "GUSD": {
          "USD": 1,
          "EUR": 0.821674,
          "BTC": 0.000018035966241721267,
          "BCH": 0.0007370228698196506,
          "ETH": 0.0002503034929852446,
          "PAX": 1,
          "BUSD": 1,
          "USDC": 1,
          "XRP": 0.6994327600316144,
          "DOGE": 1.9960079840319362,
          "DAI": 0.9990319380520276,
          "WBTC": 0.000018012422807762058
        },
        "PAX": {
          "USD": 1,
          "EUR": 0.821674,
          "BTC": 0.000018035966241721267,
          "BCH": 0.0007370228698196506,
          "ETH": 0.0002503034929852446,
          "GUSD": 1,
          "BUSD": 1,
          "USDC": 1,
          "XRP": 0.6994327600316144,
          "DOGE": 1.9960079840319362,
          "DAI": 0.9990319380520276,
          "WBTC": 0.000018012422807762058
        },
        "BUSD": {
          "USD": 1,
          "EUR": 0.821674,
          "BTC": 0.000018035966241721267,
          "BCH": 0.0007370228698196506,
          "ETH": 0.0002503034929852446,
          "GUSD": 1,
          "PAX": 1,
          "USDC": 1,
          "XRP": 0.6994327600316144,
          "DOGE": 1.9960079840319362,
          "DAI": 0.9990319380520276,
          "WBTC": 0.000018012422807762058
        },
        "USDC": {
          "USD": 1,
          "EUR": 0.821674,
          "BTC": 0.000018035966241721267,
          "BCH": 0.0007370228698196506,
          "ETH": 0.0002503034929852446,
          "GUSD": 1,
          "PAX": 1,
          "BUSD": 1,
          "XRP": 0.6994327600316144,
          "DOGE": 1.9960079840319362,
          "DAI": 0.9990319380520276,
          "WBTC": 0.000018012422807762058
        },
        "XRP": {
          "USD": 1.4253776249999999,
          "EUR": 1.17088545,
          "BTC": 0.00002570806272620483,
          "BCH": 0.0010505359077542177,
          "ETH": 0.0003567769983605121,
          "GUSD": 1.4253776249999999,
          "PAX": 1.4253776249999999,
          "BUSD": 1.4253776249999999,
          "USDC": 1.4253776249999999,
          "DOGE": 2.845065119760479,
          "DAI": 1.423997771159746,
          "WBTC": 0.00002567450444222371
        },
        "DOGE": {
          "USD": 0.5002839,
          "EUR": 0.4110702732486,
          "BTC": 0.000009023103531676658,
          "BCH": 0.0003687206757025671,
          "ETH": 0.00012522280765428083,
          "GUSD": 0.5002839,
          "PAX": 0.5002839,
          "BUSD": 0.5002839,
          "USDC": 0.5002839,
          "XRP": 0.3499149489763802,
          "DAI": 0.49979959419322684,
          "WBTC": 0.000009011325130716152
        },
        "DAI": {
          "USD": 1.000968,
          "EUR": 0.822469380432,
          "BTC": 0.000018053425057043255,
          "BCH": 0.0007377363079576361,
          "ETH": 0.00025054578676645436,
          "GUSD": 1.000968,
          "PAX": 1.000968,
          "BUSD": 1.000968,
          "USDC": 1.000968,
          "XRP": 0.7001098109433249,
          "DOGE": 1.9979401197604791,
          "WBTC": 0.000018029858833039973
        },
        "WBTC": {
          "USD": 55466.58,
          "EUR": 45575.44665492,
          "BTC": 1.000393364423732,
          "BCH": 40.88013797068123,
          "ETH": 13.883478717945511,
          "GUSD": 55466.58,
          "PAX": 55466.58,
          "BUSD": 55466.58,
          "USDC": 55466.58,
          "XRP": 38795.14313891434,
          "DOGE": 110711.73652694612,
          "DAI": 55412.88491451783
        }
     },
     "minerFees": {
        "BTC": {
          "satoshisPerByte": 79.151,
          "totalFee": 11600
        },
        "BCH": {
          "satoshisPerByte": 0,
          "totalFee": 0
        },
        "ETH": {
          "satoshisPerByte": 0,
          "totalFee": 0
        },
        "GUSD": {
          "satoshisPerByte": 0,
          "totalFee": 0
        },
        "PAX": {
          "satoshisPerByte": 0,
          "totalFee": 0
        },
        "BUSD": {
          "satoshisPerByte": 0,
          "totalFee": 0
        },
        "USDC": {
          "satoshisPerByte": 0,
          "totalFee": 0
        },
        "XRP": {
          "satoshisPerByte": 0,
          "totalFee": 0
        },
        "DOGE": {
          "satoshisPerByte": 0,
          "totalFee": 0
        },
        "DAI": {
          "satoshisPerByte": 0,
          "totalFee": 0
        },
        "WBTC": {
          "satoshisPerByte": 0,
          "totalFee": 0
        }
     },
     "shopper": {},
     "jsonPayProRequired": false,
     "supportedTransactionCurrencies": {
        "BTC": {
          "enabled": true
        },
        "BCH": {
          "enabled": true
        },
        "ETH": {
          "enabled": true
        },
        "GUSD": {
          "enabled": true
        },
        "PAX": {
          "enabled": true
        },
        "BUSD": {
          "enabled": true
        },
        "USDC": {
          "enabled": true
        },
        "XRP": {
          "enabled": true
        },
        "DOGE": {
          "enabled": true
        },
        "DAI": {
          "enabled": true
        },
        "WBTC": {
          "enabled": true
        }
     },
     "paymentCodes": {
        "BTC": {
          "BIP72b": "bitcoin:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A",
          "BIP73": "https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
        },
        "BCH": {
          "BIP72b": "bitcoincash:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A",
          "BIP73": "https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
        },
        "ETH": {
          "EIP681": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
        },
        "GUSD": {
          "EIP681b": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
        },
        "PAX": {
          "EIP681b": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
        },
        "BUSD": {
          "EIP681b": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
        },
        "USDC": {
          "EIP681b": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
        },
        "XRP": {
          "BIP72b": "ripple:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A",
          "BIP73": "https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A",
          "RIP681": "https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
        },
        "DOGE": {
          "BIP72b": "dogecoin:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A",
          "BIP73": "https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
        },
        "DAI": {
          "EIP681b": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
        },
        "WBTC": {
          "EIP681b": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
        }
     },
     "token": "Svbfdow1xXc6chtQB3GVKqyRVhyLMqn3nhMhyTtf9T9vTCDKrVfdoA7n94nZUECZf"
  }
}

The response to a create invoice request and the response to a get invoice request are all identical JSON representations of the invoice object.

Check the full Invoice resource description via the REST API reference for more information.

Updated about 2 years ago