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

# Refunds

The body of the IPNs sent by BitPay is a JSON-formatted string (`Content-Type: application/json`) and comes in 2 different formats. The extended format is used by default for the refund resource.

## Extended IPN Format

### Headers

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

### Body

> 📘 Fields containing \* are only sent on webhooks that occur AFTER `refund_created`

<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-refunds-extended-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-refunds-extended-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">Webhook data object, containing refund parameters</div>
      </td>
      <td>
        <code>object</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>id</code>
        <div class="param-info">BitPay refund ID</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>invoice</code>
        <div class="param-info">BitPay invoice ID associated to the refund</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>supportRequest</code> <b>*</b>
        <div class="param-info">BitPay support request ID associated to the refund</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>status</code>
        <div class="param-info">Refund lifecycle status of the request (refer to status field in <a href="#rest-api-resources-refunds-resource">refunds resource</a>)</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>amount</code>
        <div class="param-info">Amount to be refunded in the <code>currency</code> of the associated invoice</div>
      </td>
      <td>
        <code>number</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>currency</code>
        <div class="param-info">Currency used for the refund, the same as the currency used to create the associated invoice</div>
      </td>
      <td>
        <code>string</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>lastRefundNotification</code> <b>*</b>
        <div class="param-info">Timestamp of last notification sent to customer about refund</div>
      </td>
      <td>
        <code>date</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>refundFee</code>
        <div class="param-info">The amount of refund fee expressed in terms of pricing currency</div>
      </td>
      <td>
        <code>number</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>immediate</code>
        <div class="param-info">Whether funds should be removed from merchant ledger immediately on submission or at time of processing</div>
      </td>
      <td>
        <code>boolean</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>buyerPaysRefundFee</code>
        <div class="param-info">Whether the buyer should pay the refund fee (default is the merchant)</div>
      </td>
      <td>
        <code>boolean</code>
      </td>
    </tr>
    <tr>
      <td class="child">
        <code>requestDate</code>
        <div class="param-info">Timestamp the refund request was created</div>
      </td>
      <td>
        <code>date</code>
      </td>
    </tr>
  </tbody>
</table>
`}</HTMLBlock>

```json Example of IPN using the extended format
{
  "event": {
    "code": 7002,
    "name": "refund_pending"
  },
  "data": {
    "id": "GZBBLcsgQamua3PN8GX92s",
    "invoice": "Wp9cpGphCz7cSeFh6MSYpb",
    "supportRequest": "XuuYtZfTw7G99Ws3z38kWZ",
    "status": "pending",
    "amount": 6,
    "currency": "USD",
    "lastRefundNotification": "2022-01-11T16:58:23.967Z",
    "refundFee": 2.31,
    "immediate": false,
    "buyerPaysRefundFee": true,
    "requestDate": "2022-01-11T16:58:23.000Z"
  }
}
```

## Webhook Notification Codes

Codes for refund events with webhook notifications

<HTMLBlock>{`
<table class="table">
  <tbody>
    <tr>
      <th>BitPay code</th>
      <th>Name</th>
      <th>Purpose</th>
    </tr>
    <tr>
      <td>7001</td>
      <td><code>"refund_created"</code></td>
      <td>Received after refund request creation</td>
    </tr>
    <tr>
      <td>7002</td>
      <td><code>"refund_pending"</code></td>
      <td>Received after customer has provided refund address</td>
    </tr>
    <tr>
      <td>7003</td>
      <td><code>"refund_success"</code></td>
      <td>Received after refund request has executed and funds have been paid out to customer</td>
    </tr>
    <tr>
      <td>7004</td>
      <td><code>"refund_failure"</code></td>
      <td>Received after a refund request fails during execution</td>
    </tr>
  </tbody>
</table>
`}</HTMLBlock>