Creating Invoices
An invoice is created by sending an HTTP POST message to bitpay.com/invoices with the details of the invoice passed in the body of the request.
The body of the request must be JSON encoded and the request shall have the following HTTP headers:
content-type
must be set toapplication/json
x-accept-version
must be set to2.0.0
On successful creation, the invoice details will be provided in a JSON encoded response.
If there is an error, you will receive a JSON encoded error response. All error responses will have an error field that is an object with two fields called type and message. A merchant is restricted to creating no more than 100 invoices per hour (there are also per second and per minute limits). The fields in the request are described below.
Required POST Fields
price
price
This is the amount that is required to be collected from the buyer. Note, if this is specified in a currency other than BTC, the price will be converted into BTC at market exchange rates to determine the amount collected from the buyer.
currency
currency
This is the currency code set for the price setting. Supported pricing currencies include USD, EUR, BTC, and all currencies listed on our BitPay Exchange Rates page.
token
token
The API token can be retrieved from the BitPay Dashboard or using the Tokens resource via the REST API (see the full API reference - Request an API token).
Optional Payment Notification (IPN) Fields
The BitPay invoice service can be configured to send JSON-encoded POST callbacks to a merchant-provided URL endpoint. Settings for this capability are described below.
posData
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, "affiliate" : "spring112" }'
notificationURL
URL to which BitPay sends webhook notifications, HTTPS is mandatory. BitPay sends IPN callback to this URL when the invoice status changes.
transactionSpeed
transactionSpeed
This is a risk mitigation parameter for the merchant to configure how they want to fulfill orders depending on the number of block confirmations for the transaction made by the consumer on the selected cryptocurrency (BTC, BCH, ETH, XRP, etc). For instance, with a invoice paid in Bitcoin (BTC):
high
An invoice is considered to be confirmed
immediately upon receipt of payment.
medium
An invoice is considered to be confirmed
after 1 block confirmation (~10 minutes).
low
An invoice is considered to be confirmed
after 6 block confirmations (~1 hour).
Note:
- If not set on the invoice,
transactionSpeed
will default to your account-level order settings. - orders are always posted to your BitPay Account Summary for settlement after 6 block confirmations (regardless of this setting).
Optional Order Handling Fields
redirectURL
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.
closeURL
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.
autoRedirect
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.
Optional Display Information
orderId
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 invoiceId.
itemDesc
itemDesc
Invoice description - will be added as a line item on the BitPay checkout page, under the merchant name.
Buyer object
The buyer object can be used by the merchant to pass customer information on the BitPay invoice. The following parameters are available for this JSON object:
name
address1
address2
locality
region
postalCode
country
email
phone
BitPay Server Response
{
"facade": "merchant/invoice",
"data": {
"url": "https://bitpay.com/invoice?id=G3viJEJgE8Jk2oekSdgT2A",
"status": "new",
"price": 10,
"currency": "USD",
"orderId": "20210511_fghij",
"invoiceTime": 1620733980748,
"expirationTime": 1620734880748,
"currentTime": 1620733980807,
"id": "G3viJEJgE8Jk2oekSdgT2A",
"lowFeeDetected": false,
"amountPaid": 0,
"displayAmountPaid": "0",
"exceptionStatus": false,
"targetConfirmations": 6,
"transactions": [],
"transactionSpeed": "medium",
"buyer": {
"email": "[email protected]"
},
"redirectURL": "https://merchantwebsite.com/shop/return",
"closeURL": "https://merchantwebsite.com/shop/cancel",
"refundAddresses": [],
"refundAddressRequestPending": false,
"buyerProvidedEmail": "[email protected]",
"buyerProvidedInfo": {
"emailAddress": "[email protected]"
},
"paymentSubtotals": {
"BTC": 18000,
"BCH": 739100,
"ETH": 2505000000000000,
"GUSD": 1000,
"PAX": 10000000000000000000,
"BUSD": 10000000000000000000,
"USDC": 10000000,
"XRP": 7015685,
"DOGE": 1998865000,
"DAI": 9990000000000000000,
"WBTC": 18000
},
"paymentTotals": {
"BTC": 29600,
"BCH": 739100,
"ETH": 2505000000000000,
"GUSD": 1000,
"PAX": 10000000000000000000,
"BUSD": 10000000000000000000,
"USDC": 10000000,
"XRP": 7015685,
"DOGE": 1998865000,
"DAI": 9990000000000000000,
"WBTC": 18000
},
"paymentDisplayTotals": {
"BTC": "0.000296",
"BCH": "0.007391",
"ETH": "0.002505",
"GUSD": "10.00",
"PAX": "10.00",
"BUSD": "10.00",
"USDC": "10.00",
"XRP": "7.015685",
"DOGE": "19.988650",
"DAI": "9.99",
"WBTC": "0.000180"
},
"paymentDisplaySubTotals": {
"BTC": "0.000180",
"BCH": "0.007391",
"ETH": "0.002505",
"GUSD": "10.00",
"PAX": "10.00",
"BUSD": "10.00",
"USDC": "10.00",
"XRP": "7.015685",
"DOGE": "19.988650",
"DAI": "9.99",
"WBTC": "0.000180"
},
"exchangeRates": {
"BTC": {
"USD": 55413.609335,
"EUR": 45540.39841,
"BCH": 40.84109737914668,
"ETH": 13.870219975470258,
"GUSD": 55413.609335,
"PAX": 55413.609335,
"BUSD": 55413.609335,
"USDC": 55413.609335,
"XRP": 38758.09372049268,
"DOGE": 110606.00665668662,
"DAI": 55359.96552840298,
"WBTC": 0.9981333606461704
},
"BCH": {
"USD": 1352.90925,
"EUR": 1111.2150000000001,
"BTC": 0.02440102556111244,
"ETH": 0.33863791096704754,
"GUSD": 1352.90925,
"PAX": 1352.90925,
"BUSD": 1352.90925,
"USDC": 1352.90925,
"XRP": 946.2690507998013,
"DOGE": 2700.4176646706587,
"DAI": 1351.599550036015,
"WBTC": 0.024369173431532262
},
"ETH": {
"USD": 3992.672665000001,
"EUR": 3278.9696950000002,
"BTC": 0.0720117094001833,
"BCH": 2.9426910658087726,
"GUSD": 3992.672665000001,
"PAX": 3992.672665000001,
"BUSD": 3992.672665000001,
"USDC": 3992.672665000001,
"XRP": 2792.6060619837313,
"DOGE": 7969.406516966069,
"DAI": 3988.807510522304,
"WBTC": 0.07191770817497412
},
"GUSD": {
"USD": 1,
"EUR": 0.821674,
"BTC": 0.000018035966241721267,
"BCH": 0.0007370228698196506,
"ETH": 0.0002503034929852446,
"PAX": 1,
"BUSD": 1,
"USDC": 1,
"XRP": 0.6994327600316144,
"DOGE": 1.9960079840319362,
"DAI": 0.9990319380520276,
"WBTC": 0.000018012422807762058
},
"PAX": {
"USD": 1,
"EUR": 0.821674,
"BTC": 0.000018035966241721267,
"BCH": 0.0007370228698196506,
"ETH": 0.0002503034929852446,
"GUSD": 1,
"BUSD": 1,
"USDC": 1,
"XRP": 0.6994327600316144,
"DOGE": 1.9960079840319362,
"DAI": 0.9990319380520276,
"WBTC": 0.000018012422807762058
},
"BUSD": {
"USD": 1,
"EUR": 0.821674,
"BTC": 0.000018035966241721267,
"BCH": 0.0007370228698196506,
"ETH": 0.0002503034929852446,
"GUSD": 1,
"PAX": 1,
"USDC": 1,
"XRP": 0.6994327600316144,
"DOGE": 1.9960079840319362,
"DAI": 0.9990319380520276,
"WBTC": 0.000018012422807762058
},
"USDC": {
"USD": 1,
"EUR": 0.821674,
"BTC": 0.000018035966241721267,
"BCH": 0.0007370228698196506,
"ETH": 0.0002503034929852446,
"GUSD": 1,
"PAX": 1,
"BUSD": 1,
"XRP": 0.6994327600316144,
"DOGE": 1.9960079840319362,
"DAI": 0.9990319380520276,
"WBTC": 0.000018012422807762058
},
"XRP": {
"USD": 1.4253776249999999,
"EUR": 1.17088545,
"BTC": 0.00002570806272620483,
"BCH": 0.0010505359077542177,
"ETH": 0.0003567769983605121,
"GUSD": 1.4253776249999999,
"PAX": 1.4253776249999999,
"BUSD": 1.4253776249999999,
"USDC": 1.4253776249999999,
"DOGE": 2.845065119760479,
"DAI": 1.423997771159746,
"WBTC": 0.00002567450444222371
},
"DOGE": {
"USD": 0.5002839,
"EUR": 0.4110702732486,
"BTC": 0.000009023103531676658,
"BCH": 0.0003687206757025671,
"ETH": 0.00012522280765428083,
"GUSD": 0.5002839,
"PAX": 0.5002839,
"BUSD": 0.5002839,
"USDC": 0.5002839,
"XRP": 0.3499149489763802,
"DAI": 0.49979959419322684,
"WBTC": 0.000009011325130716152
},
"DAI": {
"USD": 1.000968,
"EUR": 0.822469380432,
"BTC": 0.000018053425057043255,
"BCH": 0.0007377363079576361,
"ETH": 0.00025054578676645436,
"GUSD": 1.000968,
"PAX": 1.000968,
"BUSD": 1.000968,
"USDC": 1.000968,
"XRP": 0.7001098109433249,
"DOGE": 1.9979401197604791,
"WBTC": 0.000018029858833039973
},
"WBTC": {
"USD": 55466.58,
"EUR": 45575.44665492,
"BTC": 1.000393364423732,
"BCH": 40.88013797068123,
"ETH": 13.883478717945511,
"GUSD": 55466.58,
"PAX": 55466.58,
"BUSD": 55466.58,
"USDC": 55466.58,
"XRP": 38795.14313891434,
"DOGE": 110711.73652694612,
"DAI": 55412.88491451783
}
},
"minerFees": {
"BTC": {
"satoshisPerByte": 79.151,
"totalFee": 11600
},
"BCH": {
"satoshisPerByte": 0,
"totalFee": 0
},
"ETH": {
"satoshisPerByte": 0,
"totalFee": 0
},
"GUSD": {
"satoshisPerByte": 0,
"totalFee": 0
},
"PAX": {
"satoshisPerByte": 0,
"totalFee": 0
},
"BUSD": {
"satoshisPerByte": 0,
"totalFee": 0
},
"USDC": {
"satoshisPerByte": 0,
"totalFee": 0
},
"XRP": {
"satoshisPerByte": 0,
"totalFee": 0
},
"DOGE": {
"satoshisPerByte": 0,
"totalFee": 0
},
"DAI": {
"satoshisPerByte": 0,
"totalFee": 0
},
"WBTC": {
"satoshisPerByte": 0,
"totalFee": 0
}
},
"shopper": {},
"jsonPayProRequired": false,
"supportedTransactionCurrencies": {
"BTC": {
"enabled": true
},
"BCH": {
"enabled": true
},
"ETH": {
"enabled": true
},
"GUSD": {
"enabled": true
},
"PAX": {
"enabled": true
},
"BUSD": {
"enabled": true
},
"USDC": {
"enabled": true
},
"XRP": {
"enabled": true
},
"DOGE": {
"enabled": true
},
"DAI": {
"enabled": true
},
"WBTC": {
"enabled": true
}
},
"paymentCodes": {
"BTC": {
"BIP72b": "bitcoin:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A",
"BIP73": "https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
},
"BCH": {
"BIP72b": "bitcoincash:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A",
"BIP73": "https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
},
"ETH": {
"EIP681": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
},
"GUSD": {
"EIP681b": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
},
"PAX": {
"EIP681b": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
},
"BUSD": {
"EIP681b": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
},
"USDC": {
"EIP681b": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
},
"XRP": {
"BIP72b": "ripple:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A",
"BIP73": "https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A",
"RIP681": "https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
},
"DOGE": {
"BIP72b": "dogecoin:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A",
"BIP73": "https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
},
"DAI": {
"EIP681b": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
},
"WBTC": {
"EIP681b": "ethereum:?r=https://bitpay.com/i/G3viJEJgE8Jk2oekSdgT2A"
}
},
"token": "Svbfdow1xXc6chtQB3GVKqyRVhyLMqn3nhMhyTtf9T9vTCDKrVfdoA7n94nZUECZf"
}
}
The response to a create invoice request and the response to a get invoice request are all identical JSON representations of the invoice object.
Check the full Invoice
resource description via the REST API reference for more information.
Updated almost 2 years ago