Invoices

Invoices are time-sensitive payment requests addressed to specific buyers. An invoice has a fixed price, typically denominated in fiat currency. It also has an equivalent price in the supported cryptocurrencies, calculated by BitPay, at a locked exchange rate with an expiration time of 15 minutes.

Resource

Name Type Facade
pos merchant
facade
This field indicates the facade from which the invoice is being requested:

  • "pos/invoice" if the pos facade is used to request an invoice resource
  • "merchant/invoice" if the merchant facade is used to request an invoice resource

string ✓ ✓
data
Invoice data object. The following fields from the initial POST request will be passed in the response from the server, in addition to some other fields listed in this section
object ✓ ✓
url
Web address of invoice, expires at expirationTime
string ✓ ✓
posData
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\" }\"".
string ✓ ✓
status

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.

string ✓ ✓
price
Fixed price amount for the checkout, in the "currency" of the invoice object.
number ✓ ✓
currency
ISO 4217 3-character currency code. This is the currency associated with the price field, supported currencies are available via the Currencies resource
string ✓ ✓
itemDesc
Invoice description - will be added as a line item on the BitPay checkout page, under the merchant name.
string ✓ ✓
orderId
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.
string ✓ ✓
invoiceTime
UNIX time of invoice creation, in milliseconds
number ✓ ✓
expirationTime
UNIX time when invoice is last available to be paid, in milliseconds
number ✓ ✓
currentTime
UNIX time of API call, in milliseconds
number ✓ ✓
guid
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.
string ✓ ✓
id
Invoice resource id
string ✓ ✓
lowFeeDetected
Flag to indicate if the miner fee used by the buyer is too low. Initially set to false when the invoice is created.
boolean ✓ ✓
amountPaid
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
number ✓ ✓
displayAmountPaid
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
string ✓ ✓
exceptionStatus
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.

boolean | string ✓ ✓
targetConfirmations
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
number ✓
transactions
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
array ✓
buyer
Allows merchant to pass buyer related information in the invoice object
object ✓
name
Buyer's name
string ✓
address1
Buyer's address
string ✓
address2
Buyer's appartment or suite number
string ✓
locality
Buyer's city or locality
string ✓
region
Buyer's state or province
string ✓
postalCode
Buyer's Zip or Postal Code
string ✓
country
Buyer's Country code. Format ISO 3166-1 alpha-2
string ✓
email
Buyer's email address. If provided during invoice creation, this will bypass the email prompt for the consumer when opening the invoice.
string ✓
phone
Buyer's phone number
string ✓
notify
Indicates whether a BitPay email confirmation should be sent to the buyer once he has paid the invoice
boolean ✓
redirectURL
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.
string ✓ ✓
closeURL
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.
string ✓ ✓
autoRedirect

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.

boolean ✓ ✓
refundAddresses
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.
array ✓
refundAddressRequestPending
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
boolean ✓ ✓
buyerProvidedEmail
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.
string ✓
buyerProvidedInfo
Information collected from the buyer during the process of paying an invoice. Initially this object is empty.
object ✓ ✓
name
Populated with the buyer's name address if passed in the buyer object by the merchant
string ✓ ✓
phoneNumber
Populated with the buyer's phone number if passed in the buyer object by the merchant
string ✓ ✓
sms
SMS provided by user for communications. This is only used for instances where a buyers email (primary form of buyer communication) is can not be gathered.
string ✓ ✓
smsVerified
Verification status of SMS (ie. have they passed the challenge).
boolean ✓ ✓
selectedWallet
This field contains the name of the cryptocurrency wallet selected by the shopper to complete the payment.
string ✓ ✓
selectedTransactionCurrency
This field will be populated with the cryptocurrency selected to pay the BitPay invoice, current supported values are "BTC", "BCH", "ETH", "GUSD", "PAX", "BUSD", "USDC", "XRP", "DOGE", "DAI" and "WBTC". If not yet selected, this field will not be returned.
string ✓ ✓
emailAddress
populated with the buyer's email address if passed in the buyer object, otherwise this field is not returned in the response.
string ✓
paymentSubtotals
For internal use. This field can be ignored in merchant implementations.
object ✓ ✓
paymentTotals
For internal use - This field can be ignored in merchant implementations.
object ✓ ✓
paymentDisplayTotals
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.
object ✓ ✓
paymentDisplaySubTotals
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.
object ✓ ✓
exchangeRates
Exchange rates keyed by source and target currencies.
object ✓ ✓
minerFees
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
object ✓ ✓
nonPayProPaymentReceived
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).
boolean ✓ ✓
shopper
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.
object ✓
user
If a shopper signs in on the invoice using his BitPay ID, this field will contain the unique ID assigned by BitPay to this shopper.
string ✓
billId
This field will be in the invoice object only if the invoice was generated from a bill, see the Bills resource for more information
string ✓
refundInfo
For a refunded invoice, this object will contain the details of executed refunds for the corresponding invoice.
object ✓
supportRequest
For a refunded invoice, this field will contain the refund requestId once executed.
string ✓
currency
For a refunded invoice, this field will contain the base currency selected for the refund. Typically the same as the invoice currency.
string ✓
amounts
For a refunded invoice, this object will contain the crypto currency amount refunded by BitPay to the consumer (in the selected transactionCurrency) and the equivalent refunded amount from the invoice in the given currency (thus linked to the amount debited from the merchant account to cover the refund)
object ✓
jsonPayProRequired
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
boolean ✓ ✓
merchantName
A display string for merchant identification (ex. Wal-Mart Store #1452, Bowling Green, KY).
string ✓ ✓
bitpayIdRequired
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.
boolean ✓
isCancelled
Indicates whether or not the invoice was cancelled.
boolean ✓
itemizedDetails
Object containing line item details for display.
object ✓ ✓
amount
The amount of currency.
number ✓ ✓
description
Display string for the item.
string ✓ ✓
isFee
Indicates whether or not the item is considered a fee/tax or part of the main purchase.
boolean ✓ ✓
acceptanceWindow
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).
number ✓ ✓
transactionCurrency
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".
string ✓ ✓
underpaidAmount
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.
number ✓ ✓
overpaidAmount
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.
number ✓ ✓
supportedTransactionCurrencies
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"
object ✓ ✓
paymentCodes
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 ✓ ✓
universalCodes
Object containing wallet-specific URLs for payment protocol.
object ✓ ✓
paymentString
Payment protocol URL for selected wallet, defaults to BitPay URL if no wallet selected.
string ✓ ✓
verificationLink
Link to bring user to BitPay ID flow, only present when bitpayIdRequired is true.
string ✓ ✓
token
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.
string ✓ ✓