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

# Create Refund Request

## Create a new refund request

`POST /refunds`

Facades **`MERCHANT`**

### HTTP Request

An example code of the create a new refund request

```java
Refund createRefund = bitpay.CreateRefund(invoice.Id, 1.0, null, true, false, false);
```

**Response Body Fields**

| Name                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |    Type   |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------: |
| id                     | the refund request id                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |  `string` |
| requestDate            | the date that the refund request was created (ISO-8601)                                                                                                                                                                                                                                                                                                                                                                                                                                      |  `string` |
| status                 | refund lifecycle status of the request string. `preview` - no funds deducted, refund will not proceed automatically. `created` - funds deducted/allocated if immediate, will proceed when txs are confirmed and required data is collected. `pending` - refund is in process of being fulfilled. `cancelled` - refund was canceled by merchant action. `success` - refund was successfully processed. `failure` - refund failed during processing (this is really more of an internal state) |  `string` |
| amount                 | Amount to be refunded in the currency indicated                                                                                                                                                                                                                                                                                                                                                                                                                                              |  `number` |
| currency               | reference currency used for the refund, usually the same as the currency used to create the invoice.                                                                                                                                                                                                                                                                                                                                                                                         |  `string` |
| immediate              | whether funds should be removed from merchant ledger immediately on submission or at time of processing                                                                                                                                                                                                                                                                                                                                                                                      | `boolean` |
| refundFee              | the amount of refund fee expressed in terms of pricing currency                                                                                                                                                                                                                                                                                                                                                                                                                              |  `number` |
| lastRefundNotification | the last time notification of buyer was attempted                                                                                                                                                                                                                                                                                                                                                                                                                                            |   `date`  |
| invoice                | associated invoice id                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |  `string` |
| buyerPaysRefundFee     | whether the buyer should pay the refund fee (default is `merchant`)                                                                                                                                                                                                                                                                                                                                                                                                                          | `boolean` |

### HTTP Response

```java
{
    id: 'TPxL75VtRRuoNexUaNQ8da',
    invoice: '8g6B3UsQ9QWvjqFrrYBssm',
    status: 'created',
    amount: 1,
    currency: 'USD',
    refundFee: 0.09,
    immediate: false,
    buyerPaysRefundFee: false,
    requestDate: '2021-12-21T14:42:58.000Z'
}
```

**Error Scenarios & Format**

| Name   | Description                                           |   Type   |
| ------ | ----------------------------------------------------- | :------: |
| status | will be “error” in an error scenario                  | `string` |
| code   | six digit code that maps to an error on BitPay’s side | `string` |
| data   | will be `null` in an error scenario                   | `object` |
| Name   | error message pertaining to the specific error        | `string` |

**Example error response**

```json
{
    "status": "error",
    "code": "010207",
    "data": null,
    "error": "Invalid invoice state for refund"
}
```