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 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.
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
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
- 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
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
paid followed by
confirmed and then
- low : The invoice will go from a status of
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.
- 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
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.
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 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).
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. Partially paid invoice are not credited to the merchant and instead automatically refunded to the customer.
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.