Create Refund Request

Create a new refund request

POST /refunds

Facades MERCHANT

HTTP Request

An example code of the create a new refund request

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

Response Body Fields

NameDescriptionType
idthe refund request idstring
requestDatethe date that the refund request was created (ISO-8601)string
statusrefund 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
amountAmount to be refunded in the currency indicatednumber
currencyreference currency used for the refund, usually the same as the currency used to create the invoice.string
immediatewhether funds should be removed from merchant ledger immediately on submission or at time of processingboolean
refundFeethe amount of refund fee expressed in terms of pricing currencynumber
lastRefundNotificationthe last time notification of buyer was attempteddate
invoiceassociated invoice idstring
buyerPaysRefundFeewhether the buyer should pay the refund fee (default is merchant)boolean

HTTP Response

{
    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

NameDescriptionType
statuswill be “error” in an error scenariostring
codesix digit code that maps to an error on BitPay’s sidestring
datawill be null in an error scenarioobject
Nameerror message pertaining to the specific errorstring

Example error response

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