Creating Invoices

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 message must be JSON encoded and the content-type should be set to application/json. 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.

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. Maximum string length is 100 characters. This passthru variable can be a JSON-encoded string, e.g.:

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

notificationURL

A URL to send status update messages to your server (this must be an https URL, unencrypted http URLs or any other type of URL is not supported).

BitPay will send an IPN callback to this URL when the invoice status changes.

transactionSpeed

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).

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

fullNotifications

true

Notifications will be sent on every status change.

false

Notifications are only sent when an invoice is confirmed (according to the transactionSpeed setting).

notificationEmail

BitPay will send an email to this email address when the invoice status changes.

Optional Order Handling Fields

redirectURL

This is the URL for a return link that is displayed on the receipt, to return the shopper back to your website after a successful purchase. This could be a page specific to the order, or to their account.

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

Used to display an item description to the buyer. Maximum string length is 100 characters.

itemCode

Used to display an item SKU code or part number to the buyer. Maximum string length is 100 characters.

physical

Defaults to false.

true

Indicates a physical item will be shipped (or picked up).

false

Indicates that nothing is to be shipped for this order.

Buyer Fields

These fields are used for display purposes only and will be shown on the invoice if provided. Maximum string length of each field is 100 characters.

  • buyerName
  • buyerAddress1
  • buyerAddress2
  • buyerCity
  • buyerState
  • buyerZip
  • buyerCountry
  • buyerEmail
  • buyerPhone

BitPay Server Response

{
  "id": "7MxRGVuBC1XvV138b3AqAR",
  "guid": "177005a3-2867-4c65-add8-7ab088e3c414",
  "itemDesc": "Lawncare, March",
  "invoiceTime": 1520368215297,
  "expirationTime": 1520369115297,
  "currentTime": 1520368235844,
  "url": "https://test.bitpay.com/invoice?id=7MxRGVuBC1XvV138b3AqAR",
  "posData": "{ \"ref\" : 711454, \"affiliate\" : \"spring112\" }",
  "status": "new",
  "exceptionStatus": false,
  "price": 10,
  "currency": "USD",
  "btcPrice": "0.000942", // [DEPRECATED] use 'paymentSubtotals' instead
  "paymentSubtotals": {
    "BTC": 94200,
    "BCH": 8496000
  },
  "paymentTotals": {
    "BTC": 97100,
    "BCH": 8496000
  },
  "amountPaid": 0,
  "exchangeRates": {
    "BTC": {
      "BCH": 8.997805828532702,
      "USD": 10621.01
    },
    "BCH": {
      "USD": 1177,
      "BTC": 0.11077647058823528
    }
  },
  "supportedTransactionCurrencies": {
    "BTC": {
      "enabled": true
    },
    "BCH": {
      "enabled": true
    }
  },
  "addresses": {
    "BTC": "mtXiukcxY2QjLSWGNaHdbvrvtakX4m5R1t",
    "BCH": "qz8tacx6fn0h6wwzd2k4y4ya5e2zddg0e5cm4nukfr"
  },
  "paymentCodes": {
    "BTC": {
      "BIP72b": "bitcoin:?r=https://test.bitpay.com/i/WoCy658tqHJrfa35F99gnp",
      "BIP73": "https://test.bitpay.com/i/WoCy658tqHJrfa35F99gnp"
    },
    "BCH": {
      "BIP72b": "bitcoincash:?r=https://test.bitpay.com/i/WoCy658tqHJrfa35F99gnp",
      "BIP73": "https://test.bitpay.com/i/WoCy658tqHJrfa35F99gnp"
    }
  },
  "token": "Hncf45uBVPNoiXbycHDh2cC37auMxhrxm5ijNCsTKGKfX4Y1vbjWCZvoSdciMNw5G"
}

The response to a create invoice request, the response to a get invoice request, and the content of a status update notification are all identical JSON representations of the invoice object. The fields are described below.

id

The unique id of the invoice.

invoiceTime

The time the invoice was created in milliseconds since midnight January 1, 1970. Time format is .

expirationTime

The time at which the invoice expires and no further payment will be accepted (in milliseconds since midnight January 1, 1970). Currently, all invoices are valid for 15 minutes. Time format is .

currentTime

The current time on the BitPay.com system (by subtracting the current time from the expiration time, the amount of time remaining for payment can be determined). Time format is .

url

An https URL where the invoice can be viewed.

posData

The passthrough variable provided by the merchant on the original invoice creation.

status

The current invoice base status. See Invoice States for more info. Possible states: new, paid, confirmed, complete, expired, invalid.

exceptionStatus

The current invoice extended status. See Invoice States for more info. Possible states: false, paidPartial, paidOver, paidLate.

price

The price set by the merchant (in terms of the provided currency).

currency

The code for the currency in which the invoice was priced.

btcPrice

DEPRECATED: The amount of bitcoins being requested for payment of this invoice (same as the price if the merchant set the price in BTC).

amountPaid

The total amount paid to the invoice in terms of the invoice transactionCurrency indicated in the smallest possible unit for the corresponding transactionCurrency (e.g satoshis for BTC and BCH)

paymentSubtotals

Equivalent of price for each of the supportedTransactionCurrencies. This value does not include the minerFees. The key is the currency and the value is an amount indicated in the smallest possible unit for each supported cryptocurrency (e.g satoshis for BTC and BCH)

paymentTotals

The total amount that the purchaser should pay. This is like paymentSubtotals but with the minerFees included. The key is the currency and the value is an amount indicated in the smallest possible unit for each supported cryptocurrency (e.g satoshis for BTC and BCH)

exchangeRates

exchange rates keyed by source and target currencies.

transactionCurrency

The cryptocurrency used to pay the invoice. This field will only be available after a transaction is applied to the invoice. Possible values are currently BTC or BCH.

supportedTransactionCurrencies

The currencies that may be used to pay this invoice. The object is keyed by currency code. The values are objects with an "enabled" boolean.

paymentCodes

The URIs for sending a transaction to the invoice. The first key is the transaction currency. The transaction currency maps to an object containing the payment URIs. The key of this object is the BIP number and the value is the payment URI. BIP21, BIP72, BIP72b, and BIP73 are supported.

Displaying Invoices