Invoices

The body of the IPNs sent by BitPay is a JSON-formatted string (Content-Type: application/json)) and comes in 2 different formats. The standard format is used by default for the invoice resource, and the extended format is recommended for all new implementations.

Standard IPN Format

This format is only applicable for the invoice resource.

📘

BitPay strongly advise merchants to use instead the extended format for the invoice resource by passing the parameter "extendedNotifications": true in the body of the invoice request.

Headers

HeaderValue
Acceptapplication/json
Content-Typeapplication/json

Body

Name Type
id
BitPay invoice id
 string
url
BitPay invoice URL
 string
posData
As passed by the merchant during invoice creation
 string
status
current invoice status given by the IPN, see Invoice resource for more information
 string
price
Fixed price amount for the checkout as indicated by the merchant during invoice creation, in the selected "currency"
 number
currency
ISO 4217 3-character currency code passed by the merchant during invoice creation
 string
invoiceTime
UNIX time of invoice creation, in milliseconds
 string
expirationTime
UNIX time when invoice is last available to be paid, in milliseconds
 string
currentTime
UNIX time of API call, in milliseconds
 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.

 string
buyerFields
If provided by the merchant in the buyer object during invoice creation
 object
buyerName
If provided by the merchant in the buyer object during invoice creation
 string
buyerAddress1
If provided by the merchant in the buyer object during invoice creation
 string
buyerAddress2
If provided by the merchant in the buyer object during invoice creation
 string
buyerCity
If provided by the merchant in the buyer object during invoice creation
 string
buyerState
If provided by the merchant in the buyer object during invoice creation
 string
buyerZip
If provided by the merchant in the buyer object during invoice creation
 string
buyerCountry
If provided by the merchant in the buyer object during invoice creation
 string
buyerPhone
If provided by the merchant in the buyer object during invoice creation
 string
buyerNotify
If provided by the merchant in the buyer object during invoice creation
 boolean
buyerEmail
If provided by the merchant in the buyer object during invoice creation
 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
exchangeRates
Exchange rate used for this invoice, depending on the invoice currency and the transactionCurrency selected
 object
amountPaid
The total amount paid to the invoice in terms of the invoice transactionCurrency indicated in the smallest possible unit for the corresponding transactionCurrency (e.g satoshis for BTC and BCH)
 number
orderId
As passed by the merchant during invoice creation
 string
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" or "BCH"
 string 
{
  "id": "Hpqc63wvE1ZjzeeH4kEycF",
  "url": "https://bitpay.com/invoice?id=Hpqc63wvE1ZjzeeH4kEycF",
  "status": "confirmed",
  "price": 10,
  "currency": "USD",
  "invoiceTime": 1620669854224,
  "expirationTime": 1620670754224,
  "currentTime": 1620671313184,
  "exceptionStatus": false,
  "buyerFields": {
    "buyerName": "John Doe",
    "buyerAddress1": "2630 Hegal Place",
    "buyerAddress2": "Apt 42",
    "buyerCity": "Alexandria",
    "buyerState": "VA",
    "buyerZip": "23242",
    "buyerCountry": "US",
    "buyerPhone": "555-123-456",
    "buyerNotify": true,
    "buyerEmail": "[email protected]"
  },
  "paymentSubtotals": {
    "BTC": 17500,
    "BCH": 700700,
    "ETH": 2406000000000000,
    "GUSD": 1000,
    "PAX": 10000000000000000000,
    "BUSD": 10000000000000000000,
    "USDC": 10000000,
    "XRP": 6668704,
    "DOGE": 2077327700,
    "DAI": 9990000000000000000,
    "WBTC": 17500
  },
  "paymentTotals": {
    "BTC": 29800,
    "BCH": 700700,
    "ETH": 2406000000000000,
    "GUSD": 1000,
    "PAX": 10000000000000000000,
    "BUSD": 10000000000000000000,
    "USDC": 10000000,
    "XRP": 6668704,
    "DOGE": 2077327700,
    "DAI": 9990000000000000000,
    "WBTC": 17500
  },
  "exchangeRates": {
    "BTC": {
      "USD": 57204.993195,
      "EUR": 47077.319565,
      "BCH": 39.966599499063804,
      "ETH": 13.755531957178825,
      "GUSD": 57204.993195,
      "PAX": 57204.993195,
      "BUSD": 57204.993195,
      "USDC": 57204.993195,
      "XRP": 38003.14441595195,
      "DOGE": 118682.55849585062,
      "DAI": 57120.83386098427,
      "WBTC": 1.0001084497591646
    },
    "BCH": {
      "USD": 1427.1930750000001,
      "EUR": 1173.9677250000002,
      "BTC": 0.024936271286002874,
      "ETH": 0.3431833281634361,
      "GUSD": 1427.1930750000001,
      "PAX": 1427.1930750000001,
      "BUSD": 1427.1930750000001,
      "USDC": 1427.1930750000001,
      "XRP": 948.1309499292485,
      "DOGE": 2960.981483402489,
      "DAI": 1425.0934048139654,
      "WBTC": 0.02495145570387066
    },
    "ETH": {
      "USD": 4156.600660000002,
      "EUR": 3418.000145000001,
      "BTC": 0.07262515738127348,
      "BCH": 2.904033102311154,
      "GUSD": 4156.600660000002,
      "PAX": 4156.600660000002,
      "BUSD": 4156.600660000002,
      "USDC": 4156.600660000002,
      "XRP": 2761.365509177756,
      "DOGE": 8623.652821576765,
      "DAI": 4150.4855164823275,
      "WBTC": 0.0726693809431983
    },
    "GUSD": {
      "USD": 1,
      "EUR": 0.822741,
      "BTC": 0.000017472247954960737,
      "BCH": 0.0006986557862672219,
      "ETH": 0.00024046033726966907,
      "PAX": 1,
      "BUSD": 1,
      "USDC": 1,
      "XRP": 0.664332644641825,
      "DOGE": 2.0746887966804977,
      "DAI": 0.9985288113971301,
      "WBTC": 0.000017482887312826024
    },
    "PAX": {
      "USD": 1,
      "EUR": 0.822741,
      "BTC": 0.000017472247954960737,
      "BCH": 0.0006986557862672219,
      "ETH": 0.00024046033726966907,
      "GUSD": 1,
      "BUSD": 1,
      "USDC": 1,
      "XRP": 0.664332644641825,
      "DOGE": 2.0746887966804977,
      "DAI": 0.9985288113971301,
      "WBTC": 0.000017482887312826024
    },
    "BUSD": {
      "USD": 1,
      "EUR": 0.822741,
      "BTC": 0.000017472247954960737,
      "BCH": 0.0006986557862672219,
      "ETH": 0.00024046033726966907,
      "GUSD": 1,
      "PAX": 1,
      "USDC": 1,
      "XRP": 0.664332644641825,
      "DOGE": 2.0746887966804977,
      "DAI": 0.9985288113971301,
      "WBTC": 0.000017482887312826024
    },
    "USDC": {
      "USD": 1,
      "EUR": 0.822741,
      "BTC": 0.000017472247954960737,
      "BCH": 0.0006986557862672219,
      "ETH": 0.00024046033726966907,
      "GUSD": 1,
      "PAX": 1,
      "BUSD": 1,
      "XRP": 0.664332644641825,
      "DOGE": 2.0746887966804977,
      "DAI": 0.9985288113971301,
      "WBTC": 0.000017482887312826024
    },
    "XRP": {
      "USD": 1.4995417500000001,
      "EUR": 1.2359324250000001,
      "BTC": 0.00002620036527481575,
      "BCH": 0.0010476635203867759,
      "ETH": 0.0003605803149549498,
      "GUSD": 1.4995417500000001,
      "PAX": 1.4995417500000001,
      "BUSD": 1.4995417500000001,
      "USDC": 1.4995417500000001,
      "DOGE": 3.111082468879668,
      "DAI": 1.4973356412678729,
      "WBTC": 0.000026216319436127937
    },
    "DOGE": {
      "USD": 0.48138770000000003,
      "EUR": 0.3960573976857,
      "BTC": 0.000008410925256868251,
      "BCH": 0.0003363243020428695,
      "ETH": 0.00011575464869947028,
      "GUSD": 0.48138770000000003,
      "PAX": 0.48138770000000003,
      "BUSD": 0.48138770000000003,
      "USDC": 0.48138770000000003,
      "XRP": 0.31980156383904546,
      "DAI": 0.4806794879021982,
      "WBTC": 0.0000084160469128805
    },
    "DAI": {
      "USD": 1.001472,
      "EUR": 0.8239520747519998,
      "BTC": 0.00001749796710395044,
      "BCH": 0.0006996842075846071,
      "ETH": 0.00024081429488613,
      "GUSD": 1.001472,
      "PAX": 1.001472,
      "BUSD": 1.001472,
      "USDC": 1.001472,
      "XRP": 0.6653105422947376,
      "DOGE": 2.0777427385892113,
      "WBTC": 0.000017508622122950502
    },
    "WBTC": {
      "USD": 57151.869999999995,
      "EUR": 47021.18667566999,
      "BTC": 0.9985716437296819,
      "BCH": 39.92948467149204,
      "ETH": 13.74275793579228,
      "GUSD": 57151.869999999995,
      "PAX": 57151.869999999995,
      "BUSD": 57151.869999999995,
      "USDC": 57151.869999999995,
      "XRP": 37967.85294332578,
      "DOGE": 118572.34439834024,
      "DAI": 57067.78882022329
    }
  },
  "amountPaid": 700700,
  "orderId": "20210510_fghij",
  "transactionCurrency": "BCH"
}

Extended IPN Format

This is the recommended IPN format that BitPay advises for all new implementations. This will allow merchants to get additional status notification which are not sent if the standard format is used (expired invoice, refunded invoice etc).

Headers

HeaderValue
Acceptapplication/json
Content-Typeapplication/json

Body

Name Type
event
Webhook event object
 object
code
See the list of available Webhook notification codes for more information
 number
name
See the list of available Webhook notification codes for more information
 string
data
Webhook data object, containing invoice parameters
 object
id
BitPay invoice id
 string
url
BitPay invoice URL
 string
posData
As passed by the merchant during invoice creation
 string
status
current invoice status given by the IPN, see Invoice resource for more information
 string
price
Fixed price amount for the checkout as indicated by the merchant during invoice creation, in the selected "currency"
 number
currency
ISO 4217 3-character currency code passed by the merchant during invoice creation
 string
invoiceTime
UNIX time of invoice creation, in milliseconds
 string
expirationTime
UNIX time when invoice is last available to be paid, in milliseconds
 string
currentTime
UNIX time of API call, in milliseconds
 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.

 string
buyerFields
If provided by the merchant in the buyer object during invoice creation
 object
buyerName
If provided by the merchant in the buyer object during invoice creation
 string
buyerAddress1
If provided by the merchant in the buyer object during invoice creation
 string
buyerAddress2
If provided by the merchant in the buyer object during invoice creation
 string
buyerCity
If provided by the merchant in the buyer object during invoice creation
 string
buyerState
If provided by the merchant in the buyer object during invoice creation
 string
buyerZip
If provided by the merchant in the buyer object during invoice creation
 string
buyerCountry
If provided by the merchant in the buyer object during invoice creation
 string
buyerPhone
If provided by the merchant in the buyer object during invoice creation
 string
buyerNotify
If provided by the merchant in the buyer object during invoice creation
 boolean
buyerEmail
If provided by the merchant in the buyer object during invoice creation
 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
exchangeRates
Exchange rate used for this invoice, depending on the invoice currency and the transactionCurrency selected
 object
amountPaid
The total amount paid to the invoice in terms of the invoice transactionCurrency indicated in the smallest possible unit for the corresponding transactionCurrency.
 number
orderId
As passed by the merchant during invoice creation
 string
transactionCurrency
The cryptocurrency used to pay the invoice. This field will only be available after a transaction is applied to the invoice.
 string 
{
  "event": {
    "code": 1005,
    "name": "invoice_confirmed"
  },
  "data": {
    "id": "Hpqc63wvE1ZjzeeH4kEycF",
    "url": "https://bitpay.com/invoice?id=Hpqc63wvE1ZjzeeH4kEycF",
    "status": "confirmed",
    "price": 10,
    "currency": "USD",
    "invoiceTime": 1620669854224,
    "expirationTime": 1620670754224,
    "currentTime": 1620671313184,
    "exceptionStatus": false,
    "buyerFields": {
      "buyerName": "John Doe",
      "buyerAddress1": "2630 Hegal Place",
      "buyerAddress2": "Apt 42",
      "buyerCity": "Alexandria",
      "buyerState": "VA",
      "buyerZip": "23242",
      "buyerCountry": "US",
      "buyerPhone": "555-123-456",
      "buyerNotify": true,
      "buyerEmail": "[email protected]"
    },
    "paymentSubtotals": {
      "BTC": 17500,
      "BCH": 700700,
      "ETH": 2406000000000000,
      "GUSD": 1000,
      "PAX": 10000000000000000000,
      "BUSD": 10000000000000000000,
      "USDC": 10000000,
      "XRP": 6668704,
      "DOGE": 2077327700,
      "DAI": 9990000000000000000,
      "WBTC": 17500
    },
    "paymentTotals": {
      "BTC": 29800,
      "BCH": 700700,
      "ETH": 2406000000000000,
      "GUSD": 1000,
      "PAX": 10000000000000000000,
      "BUSD": 10000000000000000000,
      "USDC": 10000000,
      "XRP": 6668704,
      "DOGE": 2077327700,
      "DAI": 9990000000000000000,
      "WBTC": 17500
    },
    "exchangeRates": {
      "BTC": {
        "USD": 57204.993195,
        "EUR": 47077.319565,
        "BCH": 39.966599499063804,
        "ETH": 13.755531957178825,
        "GUSD": 57204.993195,
        "PAX": 57204.993195,
        "BUSD": 57204.993195,
        "USDC": 57204.993195,
        "XRP": 38003.14441595195,
        "DOGE": 118682.55849585062,
        "DAI": 57120.83386098427,
        "WBTC": 1.0001084497591646
      },
      "BCH": {
        "USD": 1427.1930750000001,
        "EUR": 1173.9677250000002,
        "BTC": 0.024936271286002874,
        "ETH": 0.3431833281634361,
        "GUSD": 1427.1930750000001,
        "PAX": 1427.1930750000001,
        "BUSD": 1427.1930750000001,
        "USDC": 1427.1930750000001,
        "XRP": 948.1309499292485,
        "DOGE": 2960.981483402489,
        "DAI": 1425.0934048139654,
        "WBTC": 0.02495145570387066
      },
      "ETH": {
        "USD": 4156.600660000002,
        "EUR": 3418.000145000001,
        "BTC": 0.07262515738127348,
        "BCH": 2.904033102311154,
        "GUSD": 4156.600660000002,
        "PAX": 4156.600660000002,
        "BUSD": 4156.600660000002,
        "USDC": 4156.600660000002,
        "XRP": 2761.365509177756,
        "DOGE": 8623.652821576765,
        "DAI": 4150.4855164823275,
        "WBTC": 0.0726693809431983
      },
      "GUSD": {
        "USD": 1,
        "EUR": 0.822741,
        "BTC": 0.000017472247954960737,
        "BCH": 0.0006986557862672219,
        "ETH": 0.00024046033726966907,
        "PAX": 1,
        "BUSD": 1,
        "USDC": 1,
        "XRP": 0.664332644641825,
        "DOGE": 2.0746887966804977,
        "DAI": 0.9985288113971301,
        "WBTC": 0.000017482887312826024
      },
      "PAX": {
        "USD": 1,
        "EUR": 0.822741,
        "BTC": 0.000017472247954960737,
        "BCH": 0.0006986557862672219,
        "ETH": 0.00024046033726966907,
        "GUSD": 1,
        "BUSD": 1,
        "USDC": 1,
        "XRP": 0.664332644641825,
        "DOGE": 2.0746887966804977,
        "DAI": 0.9985288113971301,
        "WBTC": 0.000017482887312826024
      },
      "BUSD": {
        "USD": 1,
        "EUR": 0.822741,
        "BTC": 0.000017472247954960737,
        "BCH": 0.0006986557862672219,
        "ETH": 0.00024046033726966907,
        "GUSD": 1,
        "PAX": 1,
        "USDC": 1,
        "XRP": 0.664332644641825,
        "DOGE": 2.0746887966804977,
        "DAI": 0.9985288113971301,
        "WBTC": 0.000017482887312826024
      },
      "USDC": {
        "USD": 1,
        "EUR": 0.822741,
        "BTC": 0.000017472247954960737,
        "BCH": 0.0006986557862672219,
        "ETH": 0.00024046033726966907,
        "GUSD": 1,
        "PAX": 1,
        "BUSD": 1,
        "XRP": 0.664332644641825,
        "DOGE": 2.0746887966804977,
        "DAI": 0.9985288113971301,
        "WBTC": 0.000017482887312826024
      },
      "XRP": {
        "USD": 1.4995417500000001,
        "EUR": 1.2359324250000001,
        "BTC": 0.00002620036527481575,
        "BCH": 0.0010476635203867759,
        "ETH": 0.0003605803149549498,
        "GUSD": 1.4995417500000001,
        "PAX": 1.4995417500000001,
        "BUSD": 1.4995417500000001,
        "USDC": 1.4995417500000001,
        "DOGE": 3.111082468879668,
        "DAI": 1.4973356412678729,
        "WBTC": 0.000026216319436127937
      },
      "DOGE": {
        "USD": 0.48138770000000003,
        "EUR": 0.3960573976857,
        "BTC": 0.000008410925256868251,
        "BCH": 0.0003363243020428695,
        "ETH": 0.00011575464869947028,
        "GUSD": 0.48138770000000003,
        "PAX": 0.48138770000000003,
        "BUSD": 0.48138770000000003,
        "USDC": 0.48138770000000003,
        "XRP": 0.31980156383904546,
        "DAI": 0.4806794879021982,
        "WBTC": 0.0000084160469128805
      },
      "DAI": {
        "USD": 1.001472,
        "EUR": 0.8239520747519998,
        "BTC": 0.00001749796710395044,
        "BCH": 0.0006996842075846071,
        "ETH": 0.00024081429488613,
        "GUSD": 1.001472,
        "PAX": 1.001472,
        "BUSD": 1.001472,
        "USDC": 1.001472,
        "XRP": 0.6653105422947376,
        "DOGE": 2.0777427385892113,
        "WBTC": 0.000017508622122950502
      },
      "WBTC": {
        "USD": 57151.869999999995,
        "EUR": 47021.18667566999,
        "BTC": 0.9985716437296819,
        "BCH": 39.92948467149204,
        "ETH": 13.74275793579228,
        "GUSD": 57151.869999999995,
        "PAX": 57151.869999999995,
        "BUSD": 57151.869999999995,
        "USDC": 57151.869999999995,
        "XRP": 37967.85294332578,
        "DOGE": 118572.34439834024,
        "DAI": 57067.78882022329
      }
    },
    "amountPaid": 700700,
    "orderId": "20210510_fghij",
    "transactionCurrency": "BCH"
  }
}

Webhook Notification Codes

Codes for invoice events with webhook notifications

BitPay code Name Purpose
1003 "invoice_paidInFull" To notify merchant that an invoice has reached the status paid
1004 "invoice_expired" To notify a merchant that an invoice has expired without being paid
1005 "invoice_confirmed" To notify merchant that an invoice has reached the status confirmed
1006 "invoice_completed" To notify merchant that an invoice has reached the status complete
1012 "invoice_manuallyNotified" Whenever a merchant request for the last notification to be resent (see section Request a webhook to be resent).
1013 "invoice_failedToConfirm" To notify merchant that an invoice has reached the status invalid
1016 "invoice_refundComplete" To notify a merchant that a refund request has been successfully processed
1019 "invoice_declined" To notify a merchant that an invoice has been declined