---
updatedAt: 2025-12-02T00:33:36.000Z
agentTools:
  projectIndex: https://developer.bitpay.com/llms.txt
---

# 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

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

### Body

<HTMLBlock>{`
<table class="table">
    <tbody>
    <tr>
      <th>Name</th>
      <th>Type</th>
    </tr>
    <tr>
      <td>
        <code>event</code>
        <div class="param-info">Webhook event object</div>
      </td>
      <td>
        <code>object</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>code</code>
        <div class="param-info">See the list of available <a href="#notifications-webhooks-instant-payment-notifications-payouts-ipn-format-webhook-notification-codes">Webhook notification codes</a> for more information</div>
      </td>
      <td>
        <code>number</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>name</code>
        <div class="param-info">See the list of available <a href="#notifications-webhooks-instant-payment-notifications-payouts-ipn-format-webhook-notification-codes">Webhook notification codes</a> for more information</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td>
        <code>data</code>
        <div class="param-info">Payout data object.</div>
      </td>
      <td>
        <code>object</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>id</code>
        <div class="param-info">Payout id.</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>recipientId</code>
        <div class="param-info">BitPay recipient id, assigned by BitPay for a given recipient email during the onboarding process (see <a href="#rest-api-resources-recipients">Recipients resource</a>).</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>shopperId</code>
        <div class="param-info">
          <p>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.</p>
          <p>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 &amp; payouts).</p></div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>amount</code>
        <div class="param-info">The amount of the payout in the indicated <code>currency</code>. The minimum amount per instruction is <b>$5 USD</b> equivalent.</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>currency</code>
        <div class="param-info">Currency code set for the request <code>amount</code> (ISO 4217 3-character currency code).</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>ledgerCurrency</code>
        <div class="param-info"><p>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.</p>
          <p>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.</p></div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>exchangeRates</code>
        <div class="param-info">Exchange rates keyed by source and target currencies.</div>
      </td>
      <td>
        <code>array</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>email</code>
        <div class="param-info"><p>Email address of an active recipient.</p><p>Note: In the future, BitPay may allow Recipients to update the email address tied to their personal account. BitPay encourages the use of <code>recipientId</code> or <code>shopperId</code> when programatically creating payouts requests.</p></div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>reference</code>
        <div class="param-info">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.</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>label</code>
        <div class="param-info">For merchant use, pass through - can be the customer name or unique merchant reference assigned by the merchant to to the recipient.</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>notificationURL</code>
        <div class="param-info">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 &gt; General &gt; Payout Settings &gt; Payout IPN. HTTPS is mandatory.</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>notificationEmail</code>
        <div class="param-info">Merchant email address for notification of payout status change.</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>effectiveDate</code>
        <div class="param-info">Effective date and time (UTC) for the request. ISO-8601 format <code>yyyy-mm-ddThh:mm:ssZ</code>.</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>requestDate</code>
        <div class="param-info">Date and time (UTC) when BitPay received the request. ISO-8601 format <code>yyyy-mm-ddThh:mm:ssZ</code>.</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>status</code>
        <div class="param-info">Payout status, the possible values are:
          <p>
            </p><ul>
              <li><code>new</code> - initial status when the request is created.</li>
              <li><code>funded</code> - 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.</li>
              <li><code>processing</code> - the payouts switch to this status whenever the corresponding cryptocurrency transactions are broadcasted by BitPay.</li>
              <li><code>complete</code> - 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.</li>
              <li><code>cancelled</code> - when the merchant cancels a request (only possible for requests in the status <code>new</code>).</li>
            </ul>
          <p></p>
      </div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>transactions</code>
        <div class="param-info">Contains the cryptocurrency transaction details for the executed payout.</div>
      </td>
      <td>
        <code>array</code>
      </td>
    </tr>
    <tr>
      <td class="childchild">
        <code>txid</code>
        <div class="param-info">Cryptocurrency transaction hash for the executed payout.</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="childchild">
        <code>amount</code>
        <div class="param-info">Amount of cryptocurrency sent to the requested address.</div>
      </td>
      <td>
        <code>number</code>
      </td>
    </tr>
    <tr>
      <td class="childchild">
        <code>date</code>
        <div class="param-info">Date and time (UTC) when the cryptocurrency transaction is broadcasted. ISO-8601 format <code>yyyy-mm-ddThh:mm:ssZ</code>.</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
  </tbody>
</table>
`}</HTMLBlock>

```json Example - Funded
{
  "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 Example - Completed
{
  "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"
      }
    ]
  }
}
```

## Webhook Notification Codes

Codes for payout events with webhook notifications

<HTMLBlock>{`
<table class="table">
  <tbody>
    <tr>
      <th>BitPay code</th>
      <th>Name</th>
      <th>Purpose</th>
    </tr>
    <tr>
      <td>5001</td>
      <td><code>"payout_funded"</code></td>
      <td>To notify a merchant that a payout has been set to the status <code>funded</code></td>
    </tr>
    <tr>
      <td>5002</td>
      <td><code>"payout_processing"</code></td>
      <td>To notify a merchant that a payout has been set to the status <code>processing</code></td>
    </tr>
    <tr>
      <td>5003</td>
      <td><code>"payout_completed"</code></td>
      <td>To notify a merchant that a payout has been set to the status <code>complete</code></td>
    </tr>
    <tr>
      <td>5004</td>
      <td><code>"payout_cancelled"</code></td>
      <td>To notify a merchant that a payout has been set to the status <code>cancelled</code></td>
    </tr>
    <tr>
      <td>5005</td>
      <td><code>"payout_manuallyNotified"</code></td>
      <td>Whenever a merchant request for the last notification to be resent (see section <a href="#rest-api-resources-payouts-request-a-webhook-to-be-resent">Request a webhook to be resent</a>)</td>
    </tr>
  </tbody>
</table>
`}</HTMLBlock>