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

# Recipients

> 📘 If you would like to receive webhook notifications about the status of each recipient, you must submit a Recipient IPN within the merchant dashboard. This can be completed by the following flow: Settings > General > Payout Settings > Recipient 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-recipients-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-recipients-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">Recipient data object.</div>
      </td>
      <td>
        <code>object</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>email</code>
        <div class="param-info">Recipient email address</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>label</code>
        <div class="param-info">For merchant use, pass through - could be customer name or unique reference.</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>status</code>
        <div class="param-info">Recipient status, can have the following values:
        <p>
          </p><ul>
            <li><code>invited</code></li>
            <li><code>unverified</code></li>
            <li><code>verified</code></li>
            <li><code>active</code></li>
            <li><code>paused</code></li>
            <li><code>removed</code></li>
          </ul>
        <p></p>
      </div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>id</code>
        <div class="param-info">Unique recipient <code>id</code> assigned by BitPay for a given customer <code>email</code>.</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>
  </tbody>
</table>
`}</HTMLBlock>

```json Example - Verified
{
  "event": {
    "code": 4003,
    "name": "recipient_verified"
  },
  "data": {
    "id":"8Gq174SFAnQpdLDxRZCBPB",
    "shopperId":"5QZnQKyanj8o7qohDf2zC2",
    "email":"alice@email.com",
    "label":"Alice",
    "status":"verified",
  }
}
```

```json Example - Active
{
  "event": {
    "code": 4004,
    "name": "recipient_active"
  },
  "data": {
    "id":"X3icwc4tE8KJ5hEPNPpDXW",
    "shopperId":"A1G8wUmG9Br6RuNY5RTodM",
    "email":"bob@email.com",
    "label":"Bob",
    "status":"active",
  }
}
```

## Webhook Notification Codes

Codes for recipient events with webhook notifications

<HTMLBlock>{`
<table class="table">
  <tbody>
    <tr>
      <th>BitPay code</th>
      <th>Name</th>
      <th>Purpose</th>
    </tr>
    <tr>
      <td>4001</td>
      <td><code>recipient_invited</code></td>
      <td>To notify merchants that a recipient has reached the status <code>invited</code></td>
    </tr>
    <tr>
      <td>4002</td>
      <td><code>recipient_unverified</code></td>
      <td>To notify merchants that a recipient has reached the status <code>unverified</code></td>
    </tr>
    <tr>
      <td>4003</td>
      <td><code>recipient_verified</code></td>
      <td>To notify merchants that a recipient has reached the status <code>verified</code></td>
    </tr>
    <tr>
      <td>4004</td>
      <td><code>recipient_active</code></td>
      <td>To notify merchants that a recipient has reached the status <code>active</code></td>
    </tr>
    <tr>
      <td>4005</td>
      <td><code>recipient_paused</code></td>
      <td>To notify merchants that a recipient has reached the status <code>paused</code></td>
    </tr>
    <tr>
      <td>4006</td>
      <td><code>recipient_removed</code></td>
      <td>To notify merchants that a recipient has reached the status <code>removed</code></td>
    </tr>
    <tr>
      <td>4007</td>
      <td><code>recipient_manuallyNotified</code></td>
      <td>Whenever a merchant request for the last notification to be resent (see section <a href="#rest-api-resources-recipients-request-a-webhook-to-be-resent">Request a webhook to be resent</a>)</td>
    </tr>
  </tbody>
</table>
`}</HTMLBlock>