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.
An invoice starts in this state. When in this state and only in this state, payments to the associated bitcoin address are credited to the invoice. 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 refunded by BitPay to the customer.
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). Overpaid invoices are refunded by BitPay to the customer.
transactionSpeed setting of an invoice determines when an invoice is confirmed:
- For the high speed setting, it will be confirmed as soon as full payment is received on the bitcoin network (note, the invoice will go from a status of new to confirmed, bypassing the paid status).
- For the medium speed setting, the invoice is confirmed after the payment transaction has been confirmed by 1 block on the bitcoin network.
- For the low speed setting, 6 blocks on the bitcoin network are required. Invoices are considered complete after 6 blocks on the bitcoin network, therefore an invoice will go from a paid status directly to a complete status if the transaction speed is set to low.
When an invoice is complete, it means that BitPay has credited the merchant’s account for the invoice. Currently, 6 confirmation blocks on the bitcoin network are required for an invoice to be complete. Note, in the future (for qualified payers), invoices may move to a complete status immediately upon payment, in which case the invoice will move directly from a new status to a complete status.
An expired invoice is one where payment was not received and the 15 minute payment window has elapsed.
An invoice is considered invalid when it was paid, but the corresponding bitcoin transaction was not confirmed within 1 hour after receipt. It is possible that some transactions on the bitcoin network 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), depending on the invoice
The invoice is not in an exception state.
If the amount paid is less than the amount expected then the invoice is marked as being partially paid.
If the amount paid is greater than the amount expected then the invoice is marked as being overpaid.