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
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.
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.
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.:
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.
An invoice is considered to be confirmed immediately upon receipt of payment.
An invoice is considered to be confirmed after 1 block confirmation (~10 minutes).
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).
Notifications will be sent on every status change.
Notifications are only sent when an invoice is confirmed (according to the transactionSpeed setting).
BitPay will send an email to this email address when the invoice status changes.
Optional Order Handling Fields
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
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.
Used to display an item description to the buyer. Maximum string length is 100 characters.
Used to display an item SKU code or part number to the buyer. Maximum string length is 100 characters.
Defaults to false.
Indicates a physical item will be shipped (or picked up).
Indicates that nothing is to be shipped for this order.
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.
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.
The unique id of the invoice.
The time the invoice was created in milliseconds since midnight January 1, 1970. Time format is .
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 .
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 .
An https URL where the invoice can be viewed.
The passthrough variable provided by the merchant on the original invoice creation.
The current invoice base status. See Invoice States for more info. Possible states: new, paid, confirmed, complete, expired, invalid.
The current invoice extended status. See Invoice States for more info. Possible states: false, paidPartial, paidOver, paidLate.
DEPRECATED use amountPaid instead
DEPRECATED use exchangeRates instead
The price set by the merchant (in terms of the provided currency).
The 3 letter currency code in which the invoice was priced.
DEPRECATED The amount of bitcoins being requested for payment of this invoice (same as the price if the merchant set the price in BTC).
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)
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)
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)
exchange rates keyed by source and target currencies.
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.
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.
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.