Create Refund Request

Create a new refund request

POST /refunds

Facades MERCHANT

HTTP Request

An example code of the create a new refund request

let date = new Date();
let dateEnd = new Date().toISOString().split('T')[0];
let dateStart = new Date(date.setDate(date.getDate()-30)).toISOString().split('T')[0];

let firstPaidInvoice;

firstPaidInvoice = await client.GetInvoices(dateStart, dateEnd, InvoiceStatus.Complete, null, 1);
firstPaidInvoice = firstPaidInvoice.shift();

createdRefund = await client.CreateRefund(firstPaidInvoice, firstPaidInvoice.price, firstPaidInvoice.currency);

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`

{
   "id":"TPxL75VtRRuoNexUaNQ8da",
   "invoice":"8g6B3UsQ9QWvjqFrrYBssm",
   "status":"preview",
   "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

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