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 Bitcoin 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

Used to display your public order number to the buyer on the BitPay invoice. In the merchant Account Summary page, this value is used to identify the ledger entry. Maximum string length is 100 characters.

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

{
  "url": "https://test.bitpay.com/invoice?id=7MxRGVuBC1XvV138b3AqAR",
  "posData": "{ \"ref\" : 711454, \"affiliate\" : \"spring112\" }",
  "status": "new",
  "btcPrice": "0.069032",
  "btcDue": "0.069032",
  "price": 20,
  "currency": "USD",
  "exRates": {
    "USD": 289.71999999999997
  },
  "itemDesc": "Lawncare, March",
  "invoiceTime": 1426574968897,
  "expirationTime": 1426575868897,
  "currentTime": 1426574968952,
  "guid": "177005a3-2867-4c65-add8-7ab088e3c414",
  "id": "7MxRGVuBC1XvV138b3AqAR",
  "btcPaid": "0.000000",
  "rate": 289.72,
  "exceptionStatus": false,
  "paymentUrls": {
    "BIP21": "bitcoin:mjBQNNE16a6gWKkkMxc2QiLzrZVViyruUe?amount=0.069032",
    "BIP72": "bitcoin:mjBQNNE16a6gWKkkMxc2QiLzrZVViyruUe?amount=0.069032&r=https://test.bitpay.com/i/7MxRGVuBC1XvV138b3AqAR",
    "BIP72b": "bitcoin:?r=https://test.bitpay.com/i/7MxRGVuBC1XvV138b3AqAR",
    "BIP73": "https://test.bitpay.com/i/7MxRGVuBC1XvV138b3AqAR"
  },
  "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.

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.

btcPaid

The amount of bitcoin paid to the invoice.

rate

The numeric exchange rate (based on invoice currency) associated with the invoice at the time of the original purchase.

price

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

currency

The 3 letter currency code in which the invoice was priced.

btcPrice

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

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 .

Displaying Invoices