BitPay SDK Overview

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.

Payout Recipients

Merchants first need to issue email invites using the Recipients API resource. This is a required step to onboard customers asking for cryptocurrency payouts.

The recipients of the email invites will be invited to create a BitPay personal account, submit some verification documents and the cryptocurrency address to be used for the payouts. The customer journey is detailed in the Appendices.

📘

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.

Payouts

The BitPay Payout service enables businesses to payout fleets of users globally in one common format using digital currency, to any internet-connected user, regardless of country or banking status. The payout recipient could be an individual, or a company or a vendor that offered their services or payout employees.

This resource allows merchants to submit individual cryptocurrency payout requests to active bitpay recipients. The typical use case for this resource would be a company who wants to offer cryptocurrency withdrawals to their customers, like marketplaces or affiliate networks.

📘

Note

The BitPay payout service is only API based. Merchants will need to build their own implementation as there are currently no dashboard functionalities to submit payout requests.

The BitPay Payout service consists in 2 main processes:

A. Customer is invited by the merchant to signup for a BitPay personal account The Merchant first needs to invite its customers to sign up for a BitPay personal account where they will be invited to provide some documents for verifications (KYC) and provide a bitcoin withdrawal address to be used for the payouts. To do this, the Merchant will need to use the Recipients API resource.

B. Merchant sends Payout requests Once a recipient has reached the active status, the Merchant has the option to use the Payouts or PayoutBatches API resource to submit payout requests to BitPay.

  1. Merchants will need to keep an operational reserve on their BitPay account to ensure the batches are executed on the same day they are requested and will have to fund their account (via bank transfer or cryptocurrency deposit) if necessary.
  2. BitPay will only execute pending batches if the merchant has enough funds available on their BitPay merchant account. Pending payout requests are executed twice per day, 2pm & 9pm UTC.
  3. When the bitcoin transaction is fully confirmed on the network (6 block confirmations), BitPay notifies the merchant (email & webhooks) that the Payout Batch has reached the status "complete".

Bills

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

Rates

Rates are exchange rates, representing the number of fiat currency units equivalent to one BTC. You can retrieve BitPay's BBB exchange rates.

Wallets

Currencies are fiat currencies supported by BitPay.