---
updatedAt: 2026-01-21T19:44:51.000Z
agentTools:
  projectIndex: https://developer.bitpay.com/llms.txt
---

# Creating Invoices

An invoice is created by sending an HTTP POST message to [bitpay.com/invoices](https://bitpay.com/api#resource-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](https://developer.bitpay.com/reference/tokens)).

## 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 2 block confirmations (\~20 minutes).

**Note:**

* If not set on the invoice, `transactionSpeed` will default to your [account-level order settings](https://bitpay.com/dashboard/settings/edit/order).
* orders are always posted to your BitPay Account Summary for settlement after the default number of 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

```json
{
  "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": "john@doe.com"
     },
     "redirectURL": "https://merchantwebsite.com/shop/return",
     "closeURL": "https://merchantwebsite.com/shop/cancel",
     "refundAddresses": [],
     "refundAddressRequestPending": false,
     "buyerProvidedEmail": "john@doe.com",
     "buyerProvidedInfo": {
        "emailAddress": "john@doe.com"
     },
     "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](https://bitpay.com/api/#rest-api-resources-invoices-resource) for more information.