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

Header	Value
`Accept`	`application/json`
`Content-Type`	`application/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": "john@doe.com"
  },
  "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

Header	Value
`Accept`	`application/json`
`Content-Type`	`application/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": "john@doe.com"
    },
    "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`

Standard IPN Format

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

Body

Extended IPN Format

Headers

Body

Webhook Notification Codes

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.