API Integrations - Additional Information

Supplemental Materials for the Integration Page

Reference Materials

• Start here by reviewing our payment flowchart to gain an understanding of how a basic payment through BitPay will work.
• Review this page as a guide on generating keys for API usage.
  • This is relevant if you will need access to our merchant facade, because the merchant facade requires requests to be signed cryptographically. If you only need to use the API to create invoices, you can stick with the pos facade, which does not require requests to be signed. You’ll just need to create a pos facade token, which can be done manually in the merchant dashboard, and then you’ll be ready to go.

Best Practices

• After receiving a "completed" webhook, sent a GET invoice to the API to confirm the status.
• Use BitPay's branded payment marks / buttons on your website, both on product pages and at checkout. Making your customers aware of the option to pay in cryptocurrency is critical for adoption of the service.

Developer Documentation Pages

• Creating an Invoice
  • BitPay refers to an inbound cryptocurrency payment as an “invoice.” If you will be accepting payments, you will need to create invoices. This page explains the basics of creating a BitPay invoice, which will allow your customer to pay you.
• Displaying Invoices
  • This page explains options for displaying the BitPay invoice to your customer.
• Invoice States
  • This resource explains the various status options for a BitPay invoice.
• Checkout Page
  • BitPay’s recommendations on how to set up your checkout page to maximize the customer experience.
• Webhooks / IPNs
  • BitPay uses webhooks (which we call Instant Payment Notifications, or IPNs) so update you on the status of payments as they process. Note that these webhooks are unsigned, so you should always verify that a payment is completed using a new API call rather than trusting the webhooks. Simply use these to trigger your call to our API for payment status verification.

Transaction Speed Explanation

Transaction Speed is a risk mitigation parameter. It allows you to configure the timing at which you will fulfill orders in relation to the number of block confirmations for the transaction on the corresponding blockchain. Make sure you understand BitPay’s Invoice States, as it is important context here. If not set on the invoice, transactionSpeed will default to the account-level Order Settings.

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.

📘

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

Webhooks / Instant Payment Notifications (IPNs)

The below is an overview - you are encouraged to also view this page. API reference on this topic available here: https://bitpay.readme.io/reference/notifications

BitPay uses webhooks for notifications regarding invoice and refund status, as well as for recipients and payouts if you are sending cryptocurrency outbound. To receive webhooks, make sure you are providing a notificationURL when you create an invoice. This URL is where BitPay will send the webhooks.

It is important to understand that BitPay does NOT sign IPNs, so the information in the payload should never be trusted outright. Instead, the The IPN should be used as a trigger to verify the status of a specific invoice. This can be done by fetching the corresponding invoice via the api (getInvoice) using the invoice ID passed in the IPN payload.

Webhook details for invoices:

1. When a customer authorizes a transaction from their cryptocurrency wallet to pay the BitPay invoice, BitPay will immediately send you an IPN to notify you that the BitPay invoice went from the status “new” to “paid.” This status does NOT represent a payment guarantee, which is why we do not recommend using this status to finalize payment. The transaction still needs to be validated on the blockchain first.
2. Once the customer's transaction has received the initial validation on the corresponding blockchain network (for bitcoin, this means 1 block confirmation, which takes an average of 10 minutes) BitPay will send you an IPN to notify you that the invoice went from the status “paid” to “confirmed.”
3. Lastly, BitPay will send you an IPN to notify you that the invoice went from the status “confirmed” to “complete.” This means the consumer's transaction has been fully validated on the blockchain network (for bitcoin, this means 6 block confirmation which takes an average of 1 hour). This status also guarantees that the transaction will be settled to your bank account.

Basic API Resource Definitions

Tokens

Tokens are API access identifiers which are associated with a set of capabilities. A capability may be very broad, for example, retrieve the list of all exchange rates. Or a capability may be very specific, for example, refund invoice RhHwkycGaDskrEhGfXWnRG.

Invoices

Invoices are time-sensitive payment requests addressed to specific buyers. An invoice has a fixed price, typically denominated in fiat currency. It also has an equivalent price in the supported cryptocurrencies, calculated by BitPay, at a locked exchange rate with an expiration time of 15 minutes.

Refunds

Refund requests are full or partial refunds associated to an invoice. Fully paid invoices can be refunded via the merchant's authorization to issue a refund, while underpaid and overpaid invoices are automatically executed by BitPay to issue the underpayment or overpayment amount to the customer.

Settlements

Settlements are transfers of payment profits from BitPay to bank accounts and cryptocurrency wallets owned by merchants, partners, etc. This endpoint exposes reports detailing these settlements.

Ledgers

Ledgers are records of money movement.

Recipients

Recipients are individuals who are enabled to receive a payout from your business. To create payouts, you will first need to issue email invites using this resource. This is a mandatory step to onboard customers asking for cryptocurrency payouts. The recipients of the email invites will be invited to create a BitPay personal account, submit a photo of a proof of ID document (Passport, driver's license, Identity card) and provide the home address in order to be able to submit a cryptocurrency withdrawal address to be used for the payouts.

Notice: If you would like to receive webhook notifications about the status of each recipient, you must submit a Recipient IPN within the merchant dashboard. This can be completed by the following flow: Settings > General > Payout Settings > Recipient IPN

Please note: The BitPay personal account is NOT a cryptocurrency wallet, it is a personal account which allows customers to receive cryptocurrency payouts from merchants, make a larger purchase or request a refund, but also apply for additional services like the BitPay Prepaid Mastercard card. Think of it as the individual’s version of your merchant account.

Payouts

This resource allows merchants to submit cryptocurrency payouts to active bitpay recipients. The typical use cases for this resource would be a company who wants to offer cryptocurrency withdrawals to their customers, like marketplaces or affiliate networks, or for payroll purposes by creating multiple payouts at a time.

Bills

Bills are payment requests addressed to specific buyers. Bill line items have fixed prices, typically denominated in fiat currency.

Subscriptions

Subscriptions are repeat billing agreements with specific buyers. BitPay sends bill emails to buyers identified in active subscriptions according to the specified schedule.

Rates

Rates are exchange rates, representing the number of fiat currency units equivalent to one BTC.

Sessions

API sessions are an optional feature of our API which can be utilized to provide even greater security and reliability. In particular it protects against replay attacks and ensures api requests are processed in the same order they are received. An API session can be created by issuing a POST to /sessions. The server responds with a sessionId. The sessionId is used in each subsequent request along with a requestNumber. These fields, sessionId and requestNumber are included as parameters either in the URL for a GET or in the data body for POST and PUT. On the first request, the requestNumber should be 1. Each additional request should increment the requestNumber by 1. If the server receives a request out of order it will return an error. If the client does not hear back from the server because of an interruption in network connectivity or some other problem, the client may retry by sending the same request with the same requestNumber. The server will then respond with a cached copy of the data if it had already serviced that request but was interrupted when delivering it to the client. API sessions timeout after 15 minutes of inactivity. After 15 minutes, clients will get an error, and must create a new session. Clients can be programmed to handle creation of new sessions and timeouts automatically. Please see the Node.js client library for a working implementation.

Currencies

Currencies are fiat currencies supported by BitPay.

Certification Checklist

Checkout Experience

BitPay supports two methods for displaying invoices, redirect to our domain or a modal on your site. Make sure you've considered which options is best for you and implemented it properly.

Be sure you are following BitPay’s branding requirements. Due to BitPay’s recognition and trust in the cryptocurrency community, these will drive awareness of the offering and encourage usage. Check out the marketing section of this guide for more details.

• Your checkout page should make use of BitPay’s branded Payment Mark / Payment Button.
• Customers should easily recognize that BitPay is a payment option while shopping and upon entering the checkout flow.

Go through payment process to make sure it works properly and is convenient.

Invoice status handling

Confirm transaction speed is set as desired. As outlined in our developer documentation, low speed minimizes risk.

Make sure you understand BitPays invoice statuses (new, paid, invalid, confirmed, complete) and are fulfilling orders at the appropriate time (generally upon “completed” status).

IPNs (Webhooks)

Monitor for confirmed and complete, but understand that IPNs are not signed.

You must use GET invoice to confirm the completed status after receiving the IPN.

BitPay server expects an HTTP 200 response to IPNs.

Extended notifications can be enabled if desired.

More information available here.

Refunds

Set desired policy in your merchant dashboard under Settings.

If you are using the refunds API endpoint, your token must use our "merchant" facade.

Payment exceptions handling

Underpayments (paidPartial) will be refunded. No IPN for these.

Overpayments (paidOver) will fully pay the invoice amount, and the excess will be refunded to the user. 

Merchant Dashboard

Make sure access has been set up for any employees needing it, and that users understand how to use the dashboard for their needs.

2FA set up if desired.

Testing

If you have a test website and would like BitPay to test, please contact us to coordinate.