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": truein 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:
|
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
| 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:
|
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 |