API & SDK Documentation

Refunds

Refund requests are full or partial refunds associated to an invoice. Fully paid invoices can be refunded via the merchant's authorization to issue a refund, while underpaid and overpaid invoices are automatically executed by BitPay to issue the underpayment or overpayment amount to the customer.

Resource

Name Type
id
The ID of the refund.
 string
invoice
The ID of the invoice being refunded.
 string
supportRequest
The ID of the associated support request for the refund.
 string
refundAddress
The wallet address that the refund will return the funds to, added by the customer.
 string
txid
The transaction ID of the refund once executed.
 string
type
The type of refund.

  • full (current rate): A full refund of the amount paid at the current rate.
  • full (fixed rate): A full refund of the amount paid at the fixed rate. Note: deprecated refund implementation only
  • partial: Part of the invoice is being refunded, rather than the full invoie amount.
  • underpayment: The payment was underpaid, a refund in the amount paid will be executed.
  • overpayment: The payment was overpaid, a refund in the amount that was overpaid from the invoice price will be executed.
  • declined: The payment was declined, a refund in the full amount paid will be excuted.

 string
reference
Present only if specified in the request to create the refund. This is your reference label for this refund. It will be passed-through on each response for you to identify the refund in your system. Maximum string length is 100 characters.
 string
status
The refund lifecycle status of the request.

  • preview: No funds deducted, refund will not proceed automatically - the status must be changed via Update a Refund Request.
  • created: Funds deducted/allocated if immediate, will proceed when transactions are confirmed and the required data is collected.
  • pending: Refund is in process of being fulfilled.
  • canceled: Refund was canceled by merchant action. Immediate refunds cannot be canceled outside of preview state
  • success: Refund was successfully processed.
  • failed: Refund failed during processing (this is really more of an internal state).

 string
amount
Amount to be refunded in the invoice currency.
 number
transactionCurrency
The currency used for the invoice transaction.
 string
transactionAmount
Amount to be refunded in terms of the transaction currency.
 number
transactionRefundFee
The refund fee expressed in terms of transaction currency.
 number
currency
Reference currency used for the refund, the same as the currency used to create the invoice.
 string
lastRefundNotification
The last time notification of buyer was attempted.
 date
notificationURL
URL to which BitPay sends webhook notifications. HTTPS is mandatory.
 string
refundFee
The amount of refund fee expressed in terms of pricing currency.
 number
immediate
Whether the funds should be removed from merchant ledger immediately on submission or at the time of processing.
 boolean
buyerPaysRefundFee
Whether the buyer should pay the refund fee rather than the merchant - parameter defaults to false if not passed.
 boolean
requestDate
The date the refund was requested.
 date