---
updatedAt: 2025-09-22T17:25:19.000Z
agentTools:
  projectIndex: https://developer.bitpay.com/llms.txt
---

# Payout Webhooks

Facades: `payout`

## 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:

1. 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).
2. Merchants will be waiting for the `complete` status for a given payout request.
3. 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.
4. Merchants must use HTTPS for the `notificationURL`.
5. 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

```json 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":"john@doe.com",
        "reference":"payout_20210527",
        "label":"John Doe",
        "notificationEmail":"merchant@email.com",
        "effectiveDate":"2021-05-27T09:00:00.000Z",
        "requestDate":"2021-05-27T10:47:37.834Z",
        "status":"funded",
        "transactions":[
            
        ]
    }
}
```
```json 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":"john@doe.com",
        "reference":"payout_20210527",
        "label":"John Doe",
        "notificationEmail":"merchant@email.com",
        "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"
            }
        ]
    }
}
```