--- updatedAt: 2025-09-22T17:22:44.000Z agentTools: projectIndex: https://developer.bitpay.com/llms.txt --- # Create a Refund Request Facades: `merchant` When used on a `confirmed` invoice - invoice will decline and a refund is created for the full amount of the invoice. Refund is un-cancellable in this case as invoice has been declined. When used on a `complete` invoice - invoice remains complete but enters the refund flow for the requested refund amount. Refund is cancellable. > 📘 Note > > * Invoices will require buyer contact information, **either** an Email (recommended) or SMS, to be refunded. > * On `confirmed` invoices, the refund is worked out between BitPay and buyer as no funds have been credited to merchant ledger. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "test", "version": "1.0" }, "servers": [ { "url": "https://test.bitpay.com" } ], "security": [ {} ], "paths": { "/refunds": { "post": { "summary": "Create a Refund Request", "description": "Facades: `merchant`", "operationId": "create-a-refund-request", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Must be set to `application/json` for requests to the BitPay API", "required": true, "schema": { "type": "string", "default": "application/json" } }, { "name": "X-Accept-Version", "in": "header", "description": "Must be set to `2.0.0` for requests to the BitPay API", "required": true, "schema": { "type": "string", "default": "2.0.0" } }, { "name": "X-Identity", "in": "header", "description": "The hexadecimal public key generated from the client private key. This header is optional for this endpoint when using the public facade, and required when using a `merchant` facade token.", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "description": "The ECDSA signature of the full request URL concatenated with the request body, signed with your private key. This header is optional for this endpoint when using the public facade, and required when using a `merchant` facade token.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "invoiceId", "token" ], "properties": { "amount": { "type": "number", "description": "The amount to be refunded, denominated in the invoice original currency - partial refunds are supported", "format": "double" }, "invoiceId": { "type": "string", "description": "The ID of the invoice to refund." }, "token": { "type": "string", "description": "The API token used when originally creating the invoice." }, "preview": { "type": "boolean", "description": "Whether to create the refund request as a preview (which will not be acted on until status is updated) - parameter defaults to `false` if not passed.", "default": false }, "immediate": { "type": "boolean", "description": "Whether funds should be removed from merchant ledger immediately on submission or at time of processing - parameter defaults to `false` if not passed.", "default": false }, "buyerPaysRefundFee": { "type": "boolean", "description": "Whether the buyer should pay the refund fee rather than the merchant - parameter defaults to false if not passed.", "default": false }, "reference": { "type": "string", "description": "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." }, "guid": { "type": "string", "description": "A variable provided by the merchant and designed to be used by the merchant to correlate the refund with a refund ID in their system." } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"data\": {\n \"id\": \"WoE46gSLkJQS48RJEiNw3L\",\n \"invoice\": \"Hpqc63wvE1ZjzeeH4kEycF\",\n \"reference\": \"Test refund\",\n \"status\": \"created\",\n \"amount\": 10,\n \"transactionCurrency\": \"BTC\",\n \"transactionAmount\": 0.000594,\n \"transactionRefundFee\": 0.000002,\n \"currency\": \"USD\",\n \"lastRefundNotification\": \"2021-08-29T20:45:35.368Z\",\n \"refundFee\": 0.04,\n \"immediate\": false,\n \"buyerPaysRefundFee\": false,\n \"requestDate\": \"2021-08-29T20:45:34.000Z\"\n }\n}" } }, "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "example": "WoE46gSLkJQS48RJEiNw3L" }, "invoice": { "type": "string", "example": "Hpqc63wvE1ZjzeeH4kEycF" }, "reference": { "type": "string", "example": "Test refund" }, "status": { "type": "string", "example": "created" }, "amount": { "type": "integer", "example": 10, "default": 0 }, "transactionCurrency": { "type": "string", "example": "BTC" }, "transactionAmount": { "type": "number", "example": 0.000594, "default": 0 }, "transactionRefundFee": { "type": "number", "example": 0.000002, "default": 0 }, "currency": { "type": "string", "example": "USD" }, "lastRefundNotification": { "type": "string", "example": "2021-08-29T20:45:35.368Z" }, "refundFee": { "type": "number", "example": 0.04, "default": 0 }, "immediate": { "type": "boolean", "example": false, "default": true }, "buyerPaysRefundFee": { "type": "boolean", "example": false, "default": true }, "requestDate": { "type": "string", "example": "2021-08-29T20:45:34.000Z" } } } } } } } } }, "deprecated": false, "security": [] } } }, "x-readme": { "headers": [], "explorer-enabled": false, "proxy-enabled": true }, "x-readme-fauxas": true } ```