Invoice States

A BitPay invoice can be in one of a number of states. A payment can only be credited to a BitPay invoice when its base state is new.

There are two sets of invoice states that may be consulted: base states and exception states. Base states provide a simple and straight-forward understanding of the overall status of an invoice. Exception states provide additional details about the status of the invoice if a payment exception has occurred.

Base States

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.

This status does not represent a payment guarantee for the merchant, it only indicates the customer has broadcasted a transaction from his cryptocurrency wallet. The transaction still needs to be validated on the corresponding network (see status confirmed and complete).

confirmed

This is the invoice status to be monitored 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 confirmations achieved by the consumer's transaction in the selected cryptocurrency. This can be configured during invoice creation using the transactionSpeed parameter:

• high: The invoice is marked as confirmed by BitPay as soon as full payment is received but not yet validated on the corresponding blockchain. The invoice will go from a status of new to confirmed, bypassing the paid status. If you want an immediate notification for a payment, you can use the high speed setting. However, it makes you more susceptible to receiving fraudulent payments.
• medium (recommended for most implementations): The invoice is marked as confirmed after the transaction has received basic confirmation on the corresponding blockchain. For invoices paid in Bitcoin (BTC), this means 1 confirmation on the blockchain which takes on average 10 minutes. The invoice will go from a status of new to paid followed by confirmed and then complete
• low: The invoice will go from a status of new to paid followed by complete, thus bypassing the confirmed status. For invoices paid in Bitcoin (BTC), the status complete is reached once the customer's transaction has 6 block confirmations on the blockchain which takes on average an hour.

Note:

• When not set on the invoice, transactionSpeed will default to the account-level order settings
• Orders are only credited to the BitPay Account for settlement after the invoice reaches the status complete (regardless of the transactionSpeed 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 expired invoice is one where payment was not 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 confirmed or complete (6 confirmations for transactions on the bitcoin network for instance).

Exception States

false

The invoice is not in an exception state.

paidPartial

If the amount paid is less than the amount expected then the invoice is marked as being partially paid. Partially paid invoice are not credited to the merchant and instead automatically refunded to the customer.

paidOver

If the amount paid is greater than the amount expected then the invoice is marked as being overpaid. The overpaid amount on an invoice is not credited to the merchant and instead automatically refunded to the customer.