Invoices

Web address of invoice, expires at expirationTime

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, \"item\" : \"test_item\" }\"".

Invoice status can have the following values:

• "new": An invoice starts in this state. When in this state and only in this state, payments broadcasted by purchasers will be applied to the invoice (there is a 15 minute window for the purchaser to send a payment from their crypto wallet). If an invoice has received a partial payment, it will still reflect a status of new to the merchant. From a merchant system perspective, an invoice is either paid or not paid, partial payments are automatically refunded by BitPay to the consumer.
• "paid" As soon as payment is received it is evaluated against the invoice requested amount. If the amount paid is equal to or greater than the amount expected then the invoice is marked as being paid. To detect whether the invoice has been overpaid consult the invoice exception status (exceptionStatus parameter). The overpaid amount on an invoice is automatically refunded by BitPay to the consumer.
• "confirmed": This status can be used by merchants in order to fulfill orders placed by the consumer. Merchants can configure the timing at which BitPay sets this specific invoice status, depending on the number of confirmation achieved by the consumer's transaction in the selected cryptocurrency. This can be configured during invoice creation using the "transactionSpeed" parameter (section Create an invoice), or at account level via a dashboard setting.
• "complete": When an invoice has the status complete, it means that BitPay has credited the merchant account, in the currency indicated in the settlement settings. For instance, with invoices paid in Bitcoin (BTC), 6 confirmation blocks on the bitcoin network are required for an invoice to be complete, this takes on average 1 hour.
• "expired": An invoice reaches the expired status if no payment was received and the 15 minute payment window has elapsed.
• "invalid" An invoice is considered invalid when it was paid, but the corresponding cryptocurrency transaction was not confirmed within 1 hour on the corresponding blockchain. It is possible that some transactions can take longer than 1 hour to be included in a block. If the transaction confirms after 1 hour, BitPay will update the invoice state from "invalid" to "complete" (6 confirmations for transactions on the bitcoin network for instance).
• "declined" An invoice in the declined status is no longer eligible to be successfully completed, and the customer will be automatically contacted regarding a refund if needed. Reason for this status include cancelling an invoice before completion and the invoice remaining unconfirmed after a set time period - typically 24 hours.

Fixed price amount for the checkout, in the "currency" of the invoice object.

ISO 4217 3-character currency code. This is the currency associated with the price field, supported currencies are available via the Currencies resource

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

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 invoice id.

UNIX time of invoice creation, in milliseconds

UNIX time when invoice is last available to be paid, in milliseconds

UNIX time of API call, in milliseconds

A passthru variable provided by the merchant and designed to be used by the merchant to correlate the invoice with an order ID in their system, which can be used as a lookup variable in Retrieve Invoice by GUID.

Invoice resource id

Flag to indicate if the miner fee used by the buyer is too low. Initially set to false when the invoice is created.

Initially set to 0 when creating the invoice. It will be updated with the total amount paid to the invoice, indicated in the smallest possible unit for the corresponding transactionCurrency

Initially set to "0" when creating the invoice. It will be updated with the total amount paid to the invoice indicated in the base unit for the corresponding transactionCurrency

Initially a boolean false, this parameter will indicate if the purchaser sent too much ("paidOver") or not enough funds ("paidPartial") in the transaction to pay the BitPay invoice. Possible values are:

• false: default value (boolean) unless an exception is triggered.
• "paidPartial": (string) if the consumer did not send enough funds when paying the invoice.
• "paidOver": (string) if the consumer sent to much funds when paying the invoice.

Indicates the number of block confirmation of the crypto currency transaction which are required to credit a paid invoice to the merchant accoun. Currently the value set is set to 6 by default for BTC/BCH/XRP, 40 for DOGE and 50 for ETH/GUSD/PAX/USDC/BUSD/DAI/WBTC

Initially empty when the invoice is created. This array will be populated with the crypto currency transaction hashes linked to the invoice. For instance the consumer's transaction hash if the invoice is paid, but also the refund transaction hash if the merchant decide to issue a refund to the purchaser

Allows merchant to pass buyer related information in the invoice object

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.

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.

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.

Initially empty when the invoice is created. This field will be populated with the refund address provided by the customer if you request a refund of the specific invoice.

Initially set to false when the invoice is created, this field will be set to true once a refund request has been issued by the merchant. This flag is here to indicate that the refund request is pending action from the buyer to provide an address for the refund, via the secure link which has been automatically emailed to him

Populated with the buyer's email address if passed in the buyer object by the merchant, otherwise this field is not returned for newly created invoices. If the merchant does not pass the buyer email in the invoice request, the bitpay invoice UI will prompt the user to enter his email address and this field will be populated with the email submitted.

Information collected from the buyer during the process of paying an invoice. Initially this object is empty.

For internal use. This field can be ignored in merchant implementations.

For internal use - This field can be ignored in merchant implementations.

The total amount that the purchaser should pay as displayed on the invoice UI. This is like paymentDisplaySubTotals but with the minerFees included. The key is the currency and the value is an amount indicated in the base unit for each supported transactionCurrency.

Equivalent to price for each supported transactionCurrency, excluding minerFees. The key is the currency and the value is an amount indicated in the base unit for each supported transactionCurrency.

Exchange rates keyed by source and target currencies.

The total amount of fees that the purchaser will pay to cover BitPay's UTXO sweep cost for an invoice. The key is the currency and the value is an object containing the satoshis per byte, the total fee, and the fiat amount. This is referenced as "Network Cost" on an invoice, see this support article for more information

This boolean will be available on an invoice object once an invoice is paid and indicate if the transaction was made with a wallet using the payment protocol (true) or peer to peer (false).

This object will be available on the invoice if a shopper signs in on an invoice using his BitPay ID. See the following blogpost for more information.

This field will be in the invoice object only if the invoice was generated from a bill, see the Bills resource for more information

For a refunded invoice, this object will contain the details of executed refunds for the corresponding invoice.

Boolean set to false by default. If set to true, this means that the invoice will only accept payments from wallets which have implemented the BitPay JSON Payment Protocol

A display string for merchant identification (ex. Wal-Mart Store #1452, Bowling Green, KY).

BitPay ID is a verification process that is required when a user is making payments or receiving a refund over a given threshold, which may vary by region. This Boolean forces the invoice to require BitPay ID regardless of the price.

Indicates whether or not the invoice was cancelled.

Array of objects containing line item details for display.

Number of milliseconds that a user has to pay an invoice before it expires (0-900000). If not set, invoice will default to the account acceptanceWindow. If account acceptanceWindow is not set, invoice will default to 15 minutes (900,000 milliseconds).

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", "BCH", "ETH", "GUSD", "PAX", "BUSD", "USDC", "XRP", "DOGE", "DAI" and "WBTC".

This parameter will be returned on the invoice object if the invoice was underpaid ("exceptionStatus": "paidPartial"). It equals to the absolute difference between amountPaid and paymentTotals for the corresponding transactionCurrency used.

This parameter will be returned on the invoice object if the invoice was overpaid ("exceptionStatus": "paidOver"). It equals to the absolute difference between amountPaid and paymentTotals for the corresponding transactionCurrency used.

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 and option. An extra "reason" parameter is added in the object if a cryptocurrency is disabled on a specific invoice. If you disable a currency via the invoice parameter "paymentCurrencies", this parameter will be set to "merchantDisabledByParam"

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.

• For "BTC", "BCH" and "DOGE" - BIP72b and BIP73 are supported.
• For "ETH", "GUSD", "PAX", "BUSD", "USDC", "DAI" and "WBTC"- EIP681 is supported
• For "XRP" - RIP681, BIP72b and BIP73 is supported

Object containing wallet-specific URLs for payment protocol.

invoice resource token. This token is derived from the API token initially used to create the invoice and is tied to the specific resource id created.