API & SDK Documentation

Payouts

📘

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.

IPN Format

Headers

HeaderValue
Acceptapplication/json
Content-Typeapplication/json

Body

Name Type
event
Webhook event object
 object
code
See the list of available Webhook notification codes for more information
 number
name
See the list of available Webhook notification codes for more information
 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
shopperId

This is the unique id assigned by BitPay if the shopper used his 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 his 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 request 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 requests.

 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 request. ISO-8601 format yyyy-mm-ddThh:mm:ssZ.
 string
requestDate
Date and time (UTC) when BitPay received the request. ISO-8601 format yyyy-mm-ddThh:mm:ssZ.
 string
status
Payout status, the possible values are:

  • new - initial status when the request is created.
  • funded - if there are enough funds available on the merchant account, the requests 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 request (only possible for requests in the status new).

 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 
{
  "event": {
    "code": 5001,
    "name": "payout_funded"
  },
  "data": {
    "id": "JMwv8wQCXANoU2ZZQ9a9GH",
    "recipientId": "LDxRZCGq174SF8AnQpdBPB",
    "shopperId": "7qohDf2zZnQK5Qanj8oyC2",
    "amount": 10,
    "currency": "USD",
    "ledgerCurrency": "GBP",
    "exchangeRates": {
      "BTC": {
        "USD": 39390.47,
        "GBP": 27883.962246420004
      }
    },
    "email": "[email protected]",
    "reference": "payout_20210527",
    "label": "John Doe",
    "notificationEmail": "[email protected]",
    "effectiveDate": "2021-05-27T09:00:00.000Z",
    "requestDate": "2021-05-27T10:47:37.834Z",
    "status": "funded",
    "transactions": []
  }
}

{
  "event": {
    "code": 5003,
    "name": "payout_completed"
  },
  "data": {
    "id": "JMwv8wQCXANoU2ZZQ9a9GH",
    "recipientId": "LDxRZCGq174SF8AnQpdBPB",
    "shopperId": "7qohDf2zZnQK5Qanj8oyC2",
    "amount": 10,
    "currency": "USD",
    "ledgerCurrency": "GBP",
    "exchangeRates": {
      "BTC": {
        "USD": 39390.47,
        "GBP": 27883.962246420004
      }
    },
    "email": "[email protected]",
    "reference": "payout_20210527",
    "label": "John Doe",
    "notificationEmail": "[email protected]",
    "effectiveDate": "2021-05-27T09:00:00.000Z",
    "requestDate": "2021-05-27T10:47:37.834Z",
    "status": "complete",
    "transactions": [
      {
        "txid": "db53d7e2bf3385a31257ce09396202d9c2823370a5ca186db315c45e24594057",
        "amount": 0.000254,
        "date": "2021-05-27T11:04:23.155Z"
      }
    ]
  }
}

Webhook Notification Codes

Codes for payout events with webhook notifications

BitPay code Name Purpose
5001 "payout_funded" To notify a merchant that a payout has been set to the status funded
5002 "payout_processing" To notify a merchant that a payout has been set to the status processing
5003 "payout_completed" To notify a merchant that a payout has been set to the status complete
5004 "payout_cancelled" To notify a merchant that a payout has been set to the status cancelled
5005 "payout_manuallyNotified" Whenever a merchant request for the last notification to be resent (see section Request a webhook to be resent)