Checkout Integration

Integration Overview

This is an overview of the general steps involved when integrating BitPay cryptocurrency payments to your eCommerce website. A few things to know before you code:

BitPay maintains numerous SDKs in common code languages and various prebuilt eCommerce platform plug-ins.
It is highly advised developers use and SDK or plug-in as they handle many of the complex and repetitive tasks involved when integrating with BitPay's API.
For those preferring direct integration please review BitPay's guide to signing requests.
All development and testing should occur in BitPay's test environment before switching to product endpoints.
Cryptocurrency transactions are irreversible once "Complete" so caution should be exercised when securing applications.
BitPay provides Instant Payment Notifications so API polling is not required nor is it advised. API polling may result in your application being blocked or rate limited.

Checkout Flow

Note - BitPay uses the term “Invoice” to refer to a payment that has been generated in our system. For the purposes of this guide, we will refer to the concept of an “Invoice” in the BitPay system as simply a “payment” for the sake of simplicity.

When the customer reaches checkout (online or in person) they select “Pay with BitPay.”
Your platform calls the BitPay API to generate a new payment.
BitPay creates a payment with a “New” status. An associated URL is created and sent back to the merchant via an HTTP response.
The merchant redirects the customer to the URL provided by BitPay, where the customer can scan a QR code to enter the payment process. (In store, simply present the QR code to the customer.) This process includes selecting their wallet provider and payment currency, then authorizing the transaction.
The customer will see confirmation on their device that the payment was sent, and will be redirected back to your site if applicable.
On the BitPay end, the payment will now be changed to a status of “Paid.”
As the transaction processes on the blockchain, BitPay will transmit the latest payment status via Webhook to the merchant. See documentation on payment statuses here.
When the merchant receives the webhook indicating the payment is “Complete,” the merchant should call the BitPay API again to confirm this status. This is recommended because BitPay’s web hooks are unsigned, and therefore should not be trusted outright.
If the API call confirms the payment “complete” status, the funds have been applied to the merchant ledger, and the order can be fulfilled.