API & SDK Documentation

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.

Resource

Name Type
facade
This indicates the facade used to create the payout. When the payout facade is used to create a payout, the BitPay server returns the payout object as seen from the payout facade, that is "payout/payout".
 string
data
Payout data object.
 object
id
Payout id.
 string
recipientId
BitPay recipient id, assigned by BitPay for a given recipient email during the onboarding process (see Recipients resource).
 string
accountId
BitPay account id that is associated to the payout, assigned by BitPay for a given account during the onboarding process.
 string
shopperId

This is the unique id assigned by BitPay if the shopper used their personal BitPay account to authenticate and pay an invoice. For customers signing up for a brand new BitPay personal account, this id will only be created as part of the payout onboarding.

The same field would also be available on paid invoices if the customer signed in with their BitPay personal account before completing the payment. This can allow merchants to monitor the activity of a customer (deposits & payouts).

 string
amount
The amount of the payout in the indicated currency. The minimum amount per instruction is $5 USD equivalent.
 string
currency
Currency code set for the amount (ISO 4217 3-character currency code).
 string
ledgerCurrency

Ledger currency code set for the payout (ISO 4217 3-character currency code), it indicates on which ledger the payout will be recorded. If not provided in the request, this parameter will be set by default to the active ledger currency on your account, e.g. your settlement currency.

Supported ledger currency codes for payouts are EUR, USD, GBP, CAD, NZD, AUD, ZAR, JPY, BTC, BCH, GUSD, USDC, PAX, XRP, BUSD, DOGE, ETH, WBTC, DAI.

 string
exchangeRates
Exchange rates keyed by source and target currencies.
 array
email

Email address of an active recipient.

Note: In the future, BitPay may allow Recipients to update the email address tied to their personal account. BitPay encourages the use of recipientId or shopperId when programatically creating payouts.

 string
reference
Present only if specified by the merchant in the request. Merchants can pass their own unique identifier in this field for reconciliation purpose. Maximum string length is 100 characters.
 string
label
For merchant use, pass through - can be the customer name or unique merchant reference assigned by the merchant to to the recipient.
 string
notificationURL
URL to which BitPay sends webhook notifications. If a notificationURL is not passed during payout creation, the payout will default to using the merchant account level payout IPN if populated. This can be set by the following flow: Settings > General > Payout Settings > Payout IPN. HTTPS is mandatory.
 string
notificationEmail
Merchant email address for notification of payout status change.
 string
effectiveDate
Effective date and time (UTC) for the payout. ISO-8601 format yyyy-mm-ddThh:mm:ssZ. If not provided, defaults to date and time of creation.
 string
requestDate
Date and time (UTC) when BitPay received the payout. ISO-8601 format yyyy-mm-ddThh:mm:ssZ.
 string
dateExecuted
Date and time (UTC) when BitPay executed the payout. ISO-8601 format yyyy-mm-ddThh:mm:ssZ.
 string
status
Payout status, the possible values are:

  • new - initial status when the payout is created.
  • funded - if there are enough funds available on the merchant account, the payouts are set to funded. This happens at the daily cutoff time for payout processing, e.g. 2pm and 9pm UTC.
  • processing - the payouts switch to this status whenever the corresponding cryptocurrency transactions are broadcasted by BitPay.
  • complete - the payouts are marked as complete when the cryptocurrency transaction has reached the typical target confirmation for the corresponding asset. For instance, 6 confirmations for a bitcoin transaction.
  • cancelled - when the merchant cancels a payout (only possible for payouts in the status new).

 string
groupId
Added to the payouts made at the same time through the `Create Payout Group` request. Can be used for querying or deleting.
 string
transactions
Contains the cryptocurrency transaction details for the executed payout.
 array
txid
Cryptocurrency transaction hash for the executed payout.
 string
amount
Amount of cryptocurrency sent to the requested address.
 number
date
Date and time (UTC) when the cryptocurrency transaction is broadcasted. ISO-8601 format yyyy-mm-ddThh:mm:ssZ.
 string
confirmations
The number of confirmations the transaction has received.
 string
token
Resource token - this token is actually derived from the API token used to submit the payout and is tied to the specific payout resource id created.
 string
code
This field will be returned in case of error and contain an error code.
 number
status
Set to success in case of successful request and to error if the request failed, a description of the error will then be indicated in the message field.
 string
message
In case of error, this field will contain a description message. Set to null if the request is successful.
 string