Payout Webhooks

Overview

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).

Notification Codes

Code	Name	Purpose
5001	`payout_funded`	To notify merchants that a recipient has reached the status `invited`.
5002	`payout_processing`	To notify merchants that a recipient has reached the status `unverified`.
5003	`payout_completed`	To notify merchants that a recipient has reached the status `verified`.
5004	`payout_cancelled`	To notify merchants that a recipient has reached the status `active`.
5005	`payout_manuallyNotified`	To notify merchants that a recipient has reached the status `paused`.

Example Webhooks

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