Payout Webhooks

Webhooks are an HTTP POST message sent from the BitPay server to the merchant’s eCommerce server. The primary purpose of a webhook is to alert the merchant’s ecommerce server that the status of a resource has changed. The messages are sent to the notificationURL field when creating the payout request.

Handling

BitPay does not sign webhooks, so the information in the payload should never be trusted outright:

The webhook shall be used by the merchant as a trigger to verify the status of a specific recipient. This can be done by retrieving the corresponding recipient object, via the GET payouts/payoutId endpoint (payoutId will be provided in the body of the webhook).
Merchants will be waiting for the "complete" status for a given payout request.
The BitPay server expects an HTTP 200 response with an empty body to the webhook. Any other response is considered by BitPay as a failed delivery. The BitPay server attempts to send webhooks multiple times until the send is either successful or the BitPay server gives up.
Merchants must use HTTPS for the notificationURL.
The BitPay server attempts to send webhooks multiple times until the send is either successful or the BitPay server gives up. (schedule to be defined).

Headers

Header	Value
`Accept`	application/json
`Content-Type`	application/json

Body

Name	Description	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 (invite recipients)	`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 request in the indicated currency	`string`
→ `currency`	ISO 4217 3-character currency code. Supported transaction currencies are: https://bitpay.com/currencies	`string`
→ `ledgerCurrency`	Ledger currency code set for the payout request (ISO 4217 3-character currency code), it indicates on which ledger the payout request 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 payout requests 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.	`string`
→ `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 purposes. 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. HTTPS is mandatory.	`string`
→ `notificationEmail`	Merchant email address for notification of payout status change.	`string`
→ `effectiveDate`	Effective date and time (UTC) for the batch. ISO-8601 format `yyyy-mm-ddThh:mm:ssZ` - Note that the time of day will automatically be set to 09:00:00.000 UTC time for the given day	`string`
→ `requestDate`	Date and time (UTC) when BitPay received the batch. ISO-8601 format `yyyy-mm-ddThh:mm:ssZ`.	`string`
→ `status`	Payout request status, the possible values are: ● new - initial status when the payout batch is created ● funded - if there are enough funds available on the merchant account, the payout batches are set to funded. This happens at the daily cutoff time for payout processing, e.g. 2pm and 9pm UTC ● processing - the payout batches switch to this status whenever the corresponding cryptocurrency transactions are broadcasted by BitPay ● complete - the payout batches 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 batch (only possible for requests in the status new	`string`
→ `transactions`	Contains the cryptocurrency transaction details for the executed payout request.	`string`
→ → `txid`	Cryptocurrency transaction hash for the executed payout.	`string`
→ → `amount`	Amount of cryptocurrency sent to the requested address.	`string`
→ → `date`	Date and time (UTC) when the cryptocurrency transaction is broadcasted. ISO-8601 format `yyyy-mm-ddThh:mm:ssZ`.	`string`

Webhook notification codes

Code	Name	Purpose
`5001`	`"payout_funded"`	To notify a merchant that a payout batch has been set to the status `funded`
`5002`	`"payout_processing"`	To notify a merchant that a payout batch has been set to the status `processing`
`5003`	`"payout_completed"`	To notify a merchant that a payout batch has been set to the status `complete`
`5003`	`"payout_cancelled"`	To notify a merchant that a payout batch 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)

HTTP Response

Webhook for funded payout request

{
    "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":[
            
        ]
    }
}

Webhook for completed payout request

{
    "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"
            }
        ]
    }
}