API & SDK Documentation

Create an Invoice

post
https://test.bitpay.com/invoices

Facades: pos, merchant

Body Params
string
required

The API token can be retrieved from the dashboard (limited to pos facade) or using the Tokens resource to get access to the merchant facade. This is described in the section Request an API token).

double

Fixed price amount for the checkout, in the "currency" of the invoice object.

string
required

ISO 4217 3-character currency code. This is the currency associated with the price field, supported currencies are available via the Currencies resource.

boolean

Forces the invoice to require BitPay ID to be completed, regardless of price.

string

Display string for merchant identification (ex. Wal-Mart Store #1452, Bowling Green, KY).

string

Merchant pre-selects transaction currency on behalf of buyer.

string

Merchant pre-selects wallet on behalf of buyer.

string

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 invoice id.

string

Invoice description - will be added as a line item on the BitPay checkout page, under the merchant name.

string

"bitcoindonation" for donations, otherwise do not include the field in the request.

itemizedDetails
object

Object containing line item details for display.

string

Merchant email address for notification of invoice status change. It is also possible to configure this email via the account setting on the BitPay dashboard or disable the email notification

string

URL to which BitPay sends webhook notifications. HTTPS is mandatory.

string

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.

string

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.

boolean

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.

string

A passthru variable provided by the merchant during invoice creation 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, \"item\" : \"test_item\" }\"".

string

A passthru variable provided by the merchant and designed to be used by the merchant to correlate the invoice with an order ID in their system, which can be used as a lookup variable in Retrieve Invoice by GUID.

string

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.

  • high: The invoice is marked as "confirmed" by BitPay as soon as full payment is received but not yet validated on the corresponding blockchain. The invoice will go from a status of "new" to "confirmed", bypassing the "paid" status. If you want an immediate notification for a payment, you can use the high speed setting. However, it makes you more susceptible to receiving fraudulent payments, so it is not recommended.
  • medium: (Recommended for most merchants) The invoice is marked as "confirmed" after the transaction has received basic confirmation on the corresponding blockchain. For invoices paid in Bitcoin (BTC), this means 1 confirmation on the blockchain which takes on average 10 minutes. The invoice will go from a status of "new" to "paid" followed by "confirmed" and then "complete"
  • low: The invoice is marked as "confirmed" once BitPay has credited the funds to the merchant account. The invoice will go from a status of "new" to "paid" followed by "complete", thus bypassing the "confirmed" status. For invoices paid in Bitcoin (BTC), this means 6 confirmations on the blockchain which takes on average an hour

If not set on the invoice, transactionSpeed will default to the account-level Order Settings.

Note : orders are only credited to your BitPay Account Summary for settlement after the invoice reaches the status "complete" (regardless of this setting).

boolean

This parameter is set to true by default, meaning all standard notifications are being sent for a payment made to an invoice. If you decide to set it to false instead, only 1 webhook will be sent for each invoice paid by the consumer. This webhook will be for the "confirmed" or "complete" invoice status, depending on the transactionSpeed selected.

boolean

Allows merchants to get access to additional webhooks. For instance when an invoice expires without receiving a payment or when it is refunded. If set to true, then fullNotifications is automatically set to true. When using the extendedNotifications parameter, the webhook also have a payload slightly different from the standard webhooks.

boolean

Indicates whether items are physical goods. Alternatives include digital goods and services.

string

SMS phone number including country code i.e. +12223334444.

buyer
object

Allows merchant to pass buyer related information in the invoice object

string

If set to true, this means that the invoice will only accept payments from wallets which have implemented the BitPay JSON Payment Protocol

int32

Number of milliseconds that a user has to pay an invoice before it expires (0-900000). If not set, invoice will default to the account acceptanceWindow. If account acceptanceWindow is not set, invoice will default to 15 minutes (900,000 milliseconds).

Headers
string
required
Defaults to application/json

Must be set to application/json for requests to the BitPay API

string
required
Defaults to 2.0.0

Must be set to 2.0.0 for requests to the BitPay API

string

The hexadecimal public key generated from the client private key. This header is optional for this endpoint when using the public facade, and required when using a merchant facade token.

string

The ECDSA signature of the full request URL concatenated with the request body, signed with your private key. This header is optional for this endpoint when using the public facade, and required when using a merchant facade token.

Response

Updated 7 months ago

Language
LoadingLoading…
Response
Choose an example:
application/json

Updated 7 months ago