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 to application/json
  • x-accept-version must be set to 2.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

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

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

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

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

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

This is the URL for a return link that is displayed on the receipt, to return the shopper back to your website after a successful purchase. This could be a page specific to the order, or to their account.

Optional Display Information

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

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://test.bitpay.com/invoice?id=Ttg4UeM9jnjdh8vbMzbiW4",
    "posData": "tx46518",
    "status": "new",
    "price": 10,
    "currency": "EUR",
    "itemDesc": "Item XYZ",
    "orderId": "MerchantOrder10112",
    "invoiceTime": 1588318118648,
    "expirationTime": 1588319018648,
    "currentTime": 1588318118918,
    "id": "Ttg4UeM9jnjdh8vbMzbiW4",
    "lowFeeDetected": false,
    "amountPaid": 0,
    "displayAmountPaid": "0",
    "exceptionStatus": false,
    "targetConfirmations": 6,
    "transactions": [],
    "transactionSpeed": "medium",
    "buyer": {
      "name": "Fox Mulder",
      "address1": "2630 Hegal Place",
      "address2": "Apt 42",
      "locality": "Alexandria",
      "region": "VA",
      "postalCode": "23242",
      "country": "US",
      "email": "fox.mulder@trustno.one",
      "phone": "555-123-456",
      "notify": true
    },
    "redirectURL": "https://yourredirecturl.com",
    "refundAddresses": [],
    "refundAddressRequestPending": false,
    "buyerProvidedEmail": "fox.mulder@trustno.one",
    "buyerProvidedInfo": {
      "name": "Fox Mulder",
      "phoneNumber": "555-123-456",
      "emailAddress": "fox.mulder@trustno.one"
    },
    "paymentSubtotals": {
      "BTC": 125200,
      "BCH": 4288500,
      "ETH": 51862000000000000,
      "GUSD": 1096,
      "PAX": 10960000000000000000,
      "BUSD": 10960000000000000000,
      "USDC": 10960000,
      "XRP": 50042536
    },
    "paymentTotals": {
      "BTC": 125300,
      "BCH": 4288500,
      "ETH": 51862000000000000,
      "GUSD": 1096,
      "PAX": 10960000000000000000,
      "BUSD": 10960000000000000000,
      "USDC": 10960000,
      "XRP": 50042536
    },
    "paymentDisplayTotals": {
      "BTC": "0.001253",
      "BCH": "0.042885",
      "ETH": "0.051862",
      "GUSD": "10.96",
      "PAX": "10.96",
      "BUSD": "10.96",
      "USDC": "10.96",
      "XRP": "50.042536"
    },
    "paymentDisplaySubTotals": {
      "BTC": "0.001252",
      "BCH": "0.042885",
      "ETH": "0.051862",
      "GUSD": "10.96",
      "PAX": "10.96",
      "BUSD": "10.96",
      "USDC": "10.96",
      "XRP": "50.042536"
    },
    "exchangeRates": {
      "BTC": {
        "EUR": 7989.24,
        "USD": 8744.400000000001,
        "BCH": 34.2112676056338,
        "ETH": 41.37010928703222,
        "GUSD": 8744.400000000001,
        "PAX": 8744.400000000001,
        "BUSD": 8744.400000000001,
        "USDC": 8744.400000000001,
        "XRP": 39967.09173179761
      },
      "BCH": {
        "EUR": 233.18,
        "USD": 255.30000000000004,
        "BTC": 0.029195794799191713,
        "ETH": 1.2078346028291622,
        "GUSD": 255.30000000000004,
        "PAX": 255.30000000000004,
        "BUSD": 255.30000000000004,
        "USDC": 255.30000000000004,
        "XRP": 1166.8723433429316
      },
      "ETH": {
        "EUR": 192.81780992000003,
        "USD": 211.36000000000004,
        "BTC": 0.024170870304571723,
        "BCH": 0.8269170579029735,
        "GUSD": 211.36000000000004,
        "PAX": 211.36000000000004,
        "BUSD": 211.36000000000004,
        "USDC": 211.36000000000004,
        "XRP": 966.0404954522603
      },
      "GUSD": {
        "EUR": 0.912272,
        "USD": 1,
        "BTC": 0.00011435877320482457,
        "BCH": 0.003912363067292645,
        "ETH": 0.0047310403557742345,
        "PAX": 1,
        "BUSD": 1,
        "USDC": 1,
        "XRP": 4.570592805886924
      },
      "PAX": {
        "EUR": 0.912272,
        "USD": 1,
        "BTC": 0.00011435877320482457,
        "BCH": 0.003912363067292645,
        "ETH": 0.0047310403557742345,
        "GUSD": 1,
        "BUSD": 1,
        "USDC": 1,
        "XRP": 4.570592805886924
      },
      "BUSD": {
        "EUR": 0.912272,
        "USD": 1,
        "BTC": 0.00011435877320482457,
        "BCH": 0.003912363067292645,
        "ETH": 0.0047310403557742345,
        "GUSD": 1,
        "PAX": 1,
        "USDC": 1,
        "XRP": 4.570592805886924
      },
      "USDC": {
        "EUR": 0.912272,
        "USD": 1,
        "BTC": 0.00011435877320482457,
        "BCH": 0.003912363067292645,
        "ETH": 0.0047310403557742345,
        "GUSD": 1,
        "PAX": 1,
        "BUSD": 1,
        "XRP": 4.570592805886924
      },
      "XRP": {
        "EUR": 0.19983,
        "USD": 0.21869999999999998,
        "BTC": 0.00002501026369989513,
        "BCH": 0.0008556338028169013,
        "ETH": 0.001034678525807825,
        "GUSD": 0.21869999999999998,
        "PAX": 0.21869999999999998,
        "BUSD": 0.21869999999999998,
        "USDC": 0.21869999999999998
      }
    },
    "minerFees": {
      "BTC": {
        "satoshisPerByte": 1,
        "totalFee": 100
      },
      "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
      }
    },
    "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
      }
    },
    "paymentCodes": {
      "BTC": {
        "BIP72b": "bitcoin:?r=https://test.bitpay.com/i/Ttg4UeM9jnjdh8vbMzbiW4",
        "BIP73": "https://test.bitpay.com/i/Ttg4UeM9jnjdh8vbMzbiW4"
      },
      "BCH": {
        "BIP72b": "bitcoincash:?r=https://test.bitpay.com/i/Ttg4UeM9jnjdh8vbMzbiW4",
        "BIP73": "https://test.bitpay.com/i/Ttg4UeM9jnjdh8vbMzbiW4"
      },
      "ETH": {
        "EIP681": "ethereum:?r=https://test.bitpay.com/i/Ttg4UeM9jnjdh8vbMzbiW4"
      },
      "GUSD": {
        "EIP681b": "ethereum:?r=https://test.bitpay.com/i/Ttg4UeM9jnjdh8vbMzbiW4"
      },
      "PAX": {
        "EIP681b": "ethereum:?r=https://test.bitpay.com/i/Ttg4UeM9jnjdh8vbMzbiW4"
      },
      "BUSD": {
        "EIP681b": "ethereum:?r=https://test.bitpay.com/i/Ttg4UeM9jnjdh8vbMzbiW4"
      },
      "USDC": {
        "EIP681b": "ethereum:?r=https://test.bitpay.com/i/Ttg4UeM9jnjdh8vbMzbiW4"
      },
      "XRP": {
        "BIP72b": "ripple:?r=https://test.bitpay.com/i/Ttg4UeM9jnjdh8vbMzbiW4",
        "BIP73": "https://test.bitpay.com/i/Ttg4UeM9jnjdh8vbMzbiW4",
        "RIP681": "https://test.bitpay.com/i/Ttg4UeM9jnjdh8vbMzbiW4"
      }
    },
    "token": "ymrU3Xd2ZhQzZA8ENWkAabvPgRKMATnh62cSMCvxsscrnzZNnLCNwRtAkpYXAQzEp"
  }
}

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.

Checkout Page