API & SDK Documentation

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

HeaderValue
Acceptapplication/json
Content-Typeapplication/json

Body

📘

Fields containing * are only sent on webhooks that occur AFTER refund_created

Name Type
event
Webhook event object
 object
code
See the list of available Webhook notification codes for more information
 number
name
See the list of available Webhook notification codes for more information
 string
data
Webhook data object, containing refund parameters
 object
id
BitPay refund ID
 string
invoice
BitPay invoice ID associated to the refund
 string
supportRequest *
BitPay support request ID associated to the refund
 string
status
Refund lifecycle status of the request (refer to status field in refunds resource)
 string
amount
Amount to be refunded in the currency of the associated invoice
 number
currency
Currency used for the refund, the same as the currency used to create the associated invoice
 string
lastRefundNotification *
Timestamp of last notification sent to customer about refund
 date
refundFee
The amount of refund fee expressed in terms of pricing currency
 number
immediate
Whether funds should be removed from merchant ledger immediately on submission or at time of processing
 boolean
buyerPaysRefundFee
Whether the buyer should pay the refund fee (default is the merchant)
 boolean
requestDate
Timestamp the refund request was created
 date 
{
  "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

BitPay code Name Purpose
7001 "refund_created" Received after refund request creation
7002 "refund_pending" Received after customer has provided refund address
7003 "refund_success" Received after refund request has executed and funds have been paid out to customer
7004 "refund_failure" Received after a refund request fails during execution