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.
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.
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.
Here's a demo:
bitpay.js
to your web page:<script src="https://bitpay.com/bitpay.js"></script>
id
of the invoice as part of the request response.id
into the showInvoice
method provided by bitpay.js
:bitpay.showInvoice(id);
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.
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></p> <script language="javascript"> window.addEventListener("message", function(event) { document.getElementById("s1").innerHTML=event.data.status; }, false); </script> </body> </html>Instant Payment Notifications (IPNs)