Displaying Invoices

Because Bitcoin works as a push transaction, rather than using the traditional authorize and capture process (pull) as does a credit card, you must accomodate this in your checkout flow.

While a traditional checkout flow would collect credit card info and then present a “finalize order” page and subsequently charge the card, with Bitcoin, no details need to be collected prior to confirmation. A click on “confirm order” should present a modal or blocking payment screen which will provide a bitcoin invoice for payment, then proceed to confirmation once the payment is received.

Redirect to BitPay

The simplest integration is to simply redirect your customer to the BitPay site to complete payment, then return them to your site for order confirmation. In this case, you need only redirect your customer to the url returned in the JSON response from the /invoices endpoint.

You can do this most easily by using one of our supported integrations or directly with one of our supported libraries.

The BitPay invoice uses responsive design to ensure that the user gets optimal presentation regardless of device form factor.

Be sure that you have also set the redirectURL when generating the invoice, which will ensure that the user gets redirected to the appropriate confirmation page following payment.

You should always validate that the invoice was paid by re-querying the BitPay API, or by manually validating that it appears in your account ledger, before completing the transaction.

Modal Invoice (iFrame)

BitPay allows you display the invoice within a modal on your web page, so the shopper never has to leave your site during the checkout process.

Modal invoice demo:

  1. To use the modal invoice, add bitpay.js to your web page: 
    2. <script src="https://bitpay.com/bitpay.js"></script>
  2. When you create an invoice with a POST request to BitPay, BitPay returns the id of the invoice as part of the request response.
  3. To display the newly created invoice within a modal, pass the invoice id into the showInvoice method provided by bitpay.js:
    4. bitpay.showInvoice(id);
  4. The modal invoice will automatically update when payments have been received. In addition to the server IPN sent to your notificationURL, the modal iframe will send a message to the parent window that the status has changed.

Additional methods provided by bitpay.js include:

  • onModalWillEnter: Allows you to specify a function to be called right before the modal opens.
  • onModalWillLeave: Allows you to specify a function to be called when the user closes the modal.
  • enableTestMode: Allows you to display invoices created via https://test.bitpay.com.
bitpay.onModalWillEnter(function() {
  console.log('modal is opening');
});

bitpay.onModalWillLeave(function() {
  console.log('modal is closing');
});

bitpay.enableTestMode();

It is highly recommended that you include the email of the buyer as part of the buyerFields.buyerEmail field when creating the invoice via the BitPay API. The buyerEmail field will be used by BitPay to contact the buyer in the case of an underpayment or overpayment in order to administer a refund. If you do not provide the buyerEmail field, BitPay will prompt the user for an email address when the modal opens.

Embedded Invoice (iFrame)

BitPay also allows you to embed the invoice directly into a 500 x 150px block on your web page.

  1. When you create an invoice with a POST request to BitPay, BitPay returns the url field, which is the URL at which this invoice can be viewed.
  2. To display the embedded invoice on your page, append the code &view=iframe to the invoice URL and specify this value as the src in an iframe.
  3. The embedded invoice will automatically update when payments have been received. In addition to the server IPN sent to your notificationURL, the iframe will send a message to the parent window that the status has changed.

If your website has a dark background theme, append the code &theme=dark to the invoice URL. Note that the iframe background color is transparent.

<iframe id="bitpay_invoice_iframe"
  scrolling="no"
  allowtransparency="true"
  frameborder="0"  src='https://test.bitpay.com/invoice?id=LxuN1nQwB3UKTVuamJeLSi&view=iframe'
  style='width:500px; overflow: hidden; padding:20px; max-width:100%'>
</iframe>

Post to Parent Window

When an invoice is presented in an iframe you have an option to receive invoice status updates in the parent window. This option is useful for updating the parent window presentation or redirecting the parent window to another URL after the invoice has been paid.

When the invoice iframe receives a status update from the BitPay server the new status is posted from the invoice iframe to the parent window via the Window.postMessage method and passing {status: string} where status can be any of the Invoice States according to the descriptions provided.

Your implementation should take into consideration the browser support for this method. See CanIUse for a list of browsers supporting Window.postMessage.

Following is an HTML code example illustrating a simple interaction between an invoice iframe and its parent document.

<html>
  <head>
    <title>Parent</title>
  </head>
  <body>
    <p>Invoice status: <span id="s1"></span>
    <iframe src="https://bitpay.com/invoice?id=UbAd3j1E7ivCe5i9t88obd" style="width: 800px; height: 800px;"></iframe>
    <script language="javascript">
  window.addEventListener("message", function(event) {
      document.getElementById("s1").innerHTML=event.data.status;
  }, false);
    </script>
  </body>
</html>
Instant Payment Notifications (IPNs)