> This page is for Cash App Pay Partner API. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.cash.app/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.cash.app/_mcp/server. # Create refund POST https://api.cash.app/network/v1/refunds Content-Type: application/json Creates a refund from a merchant to a customer. - To issue a refund, provide a `payment_id` in the request. The grant must be associated with the `ON_FILE_PAYMENT` actions. To generate a grant to pass to this field, use the Customer Request API. **This endpoint is not rate limited.** Scopes: `REFUNDS_WRITE` Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/create-refund ## Servers - `https://api.cash.app/network/v1` (Production, default) - `https://sandbox.api.cash.app/network/v1` (Sandbox) ## Request ### Body (application/json) This endpoint expects an object. - `idempotency_key` (string, required) — A unique identifier which can be used by Cash App to de-duplicate retries of this request, making it idempotent. For more information, see [Idempotency](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/idempotency). - `refund` (CreateRefundRequestRefund, required) — Details about the refund to create. ## Response ### 200 OK - `refund` (Refund, required) ## Errors ### 400 Create Refund Request Bad Request Error Bad Request If a `REFUND_DECLINE_*` error is returned, the refund will still be created, but with a `DECLINED` status. This refund will then appear in the response payload. **`REFUND_DECLINE_*` errors consume one-time use grants.** This means you must repeat the Customer Request flow to get a new grant if you want to try issuing the refund again. All other errors will not consume grants. - `errors` (list of Error, required) — A list of errors that occurred while processing the request. - `refund` (Refund, optional) ## Types ### CreateRefundRequestRefund Details about the refund to create. - `amount` (integer, required) — The amount of money to refund the customer, in the lowest denomination of currency for the refund. Min value: `1` - `currency` (enum, required) — Indicates the country associated with an entity. Values are from the [ISO-4217 Alpha-3](https://www.iso.org/iso-4217-currency-codes.html) specification. Current values: - `USD`: United States Dollar - Allowed values: `USD` - `merchant_id` (string, required) — ID of the merchant to make the refund from. Min length: `1` Max length: `128` - `payment_id` (string, optional) — For refunds, this is the ID of the payment to refund. Min length: `1` Max length: `128` - `capture` (boolean, optional, default: true) — Whether or not to automatically capture the refund once it's created. Default: `true` - `reference_id` (string, optional) — A user-defined identifier for this refund, typically used to associate the refund with a record in an external system. Min length: `1` Max length: `1024` - `metadata` (map from string to string, optional) — Freeform key-value pairs of arbitrary data associated with this resource. Keys and values must be passed as strings and not contain any personally identifiable information (PII). Min keys: `0` Max keys: `50` > Note: Nested keys are not supported. ### Refund - `id` (string, required) — Unique identifier for this refund issued by Cash App. Min length: `1` Max length: `128` - `amount` (integer, required) — Amount of money to refund, in the lowest denomination of currency on the refund. Min value: `1` - `currency` (enum, required) — Indicates the country associated with an entity. Values are from the [ISO-4217 Alpha-3](https://www.iso.org/iso-4217-currency-codes.html) specification. Current values: - `USD`: United States Dollar - Allowed values: `USD` - `customer_id` (string, required) — ID of the customer that received this refund. Min length: `1` Max length: `128` - `merchant_id` (string, required) — ID of the merchant that issued this refund. Min length: `1` Max length: `128` - `status` (enum, required) — The step of the refund processing lifecycle that this refund is currently at. - `AUTHORIZED` - `CAPTURED` - `VOIDED` - `DECLINED` - Allowed values: `AUTHORIZED`, `CAPTURED`, `VOIDED`, `DECLINED` - `created_at` (datetime, required) — When this refund was created, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC). - `updated_at` (datetime, required) — When this refund was last updated, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC). - `grant_id` (string, optional) — This is currently unused and empty. Min length: `1` Max length: `256` - `payment_id` (string, optional) — This is currently unused and empty. Min length: `1` Max length: `128` - `reference_id` (string, optional) — A user-defined identifier for this refund, typically used to associate the refund with a record in an external system. Min length: `1` Max length: `1024` - `metadata` (map from string to string, optional) — Freeform key-value pairs of arbitrary data associated with this resource. Keys and values must be passed as strings and not contain any personally identifiable information (PII). Min keys: `0` Max keys: `50` > Note: Nested keys are not supported. - `decline_errors` (list of Error, optional) — If the refund was declined, contains a list of the reasons why it was declined. Min number of items: `1` ### Error Represents an error encountered during a request to the API. - `category` (enum, required) — The high-level reason the error occurred. - Allowed values: `API_ERROR`, `AUTHENTICATION_ERROR`, `BRAND_ERROR`, `DISPUTE_ERROR`, `MERCHANT_ERROR`, `INVALID_REQUEST_ERROR`, `PAYMENT_PROCESSING_ERROR`, `RATE_LIMIT_ERROR`, `WEBHOOK_ERROR`, `API_KEY_ERROR`, `GRANT_ERROR` - `code` (string, required) — A unique identifier for the specific type of error that occurred. For more information, see [Error Code Reference](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference). Min length: `1` - `detail` (string, optional) — Human-readable description of why the error occurred and how to resolve it. Min length: `1` - `field` (string, optional) — The field in the request that caused the error, using array and object dot notation. Min length: `1` ## Examples **Request** ```json { "idempotency_key": "178f2318-a335-4be2-9792-6259a8887874", "refund": { "amount": 100, "currency": "USD", "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x", "payment_id": "PWC_etdng09kyyqf5zr583v8xcs2k", "capture": true, "reference_id": "external-id", "metadata": { "key": "value" } } } ``` **Response** ```json { "refund": { "id": "PWCR_da1v3j4p3z15y47adpzzq0whj", "amount": 2500, "currency": "USD", "customer_id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY", "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x", "status": "AUTHORIZED", "created_at": "2022-01-01T12:00:00Z", "updated_at": "2022-01-05T12:00:00Z", "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50", "payment_id": "PWC_4nn21zy6t0v2yhqg5bvhk7xkq", "reference_id": "external-id", "metadata": { "key": "value" }, "decline_errors": [ { "category": "INVALID_REQUEST_ERROR", "code": "MISSING_REQUIRED_FIELD", "detail": "Missing required parameter.", "field": "field_a[2].field_b" } ] } } ``` **SDK Code** ```python Create a $1 (USD) Refund (with metadata) import requests url = "https://api.cash.app/network/v1/refunds" payload = { "idempotency_key": "178f2318-a335-4be2-9792-6259a8887874", "refund": { "amount": 100, "currency": "USD", "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x", "payment_id": "PWC_etdng09kyyqf5zr583v8xcs2k", "capture": True, "reference_id": "external-id", "metadata": { "key": "value" } } } headers = {"Content-Type": "application/json"} response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Create a $1 (USD) Refund (with metadata) const url = 'https://api.cash.app/network/v1/refunds'; const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"idempotency_key":"178f2318-a335-4be2-9792-6259a8887874","refund":{"amount":100,"currency":"USD","merchant_id":"MMI_4vxs5egfk7hmta3qx2h6rp91x","payment_id":"PWC_etdng09kyyqf5zr583v8xcs2k","capture":true,"reference_id":"external-id","metadata":{"key":"value"}}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Create a $1 (USD) Refund (with metadata) package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.cash.app/network/v1/refunds" payload := strings.NewReader("{\n \"idempotency_key\": \"178f2318-a335-4be2-9792-6259a8887874\",\n \"refund\": {\n \"amount\": 100,\n \"currency\": \"USD\",\n \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n \"payment_id\": \"PWC_etdng09kyyqf5zr583v8xcs2k\",\n \"capture\": true,\n \"reference_id\": \"external-id\",\n \"metadata\": {\n \"key\": \"value\"\n }\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Create a $1 (USD) Refund (with metadata) require 'uri' require 'net/http' url = URI("https://api.cash.app/network/v1/refunds") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = 'application/json' request.body = "{\n \"idempotency_key\": \"178f2318-a335-4be2-9792-6259a8887874\",\n \"refund\": {\n \"amount\": 100,\n \"currency\": \"USD\",\n \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n \"payment_id\": \"PWC_etdng09kyyqf5zr583v8xcs2k\",\n \"capture\": true,\n \"reference_id\": \"external-id\",\n \"metadata\": {\n \"key\": \"value\"\n }\n }\n}" response = http.request(request) puts response.read_body ``` ```java Create a $1 (USD) Refund (with metadata) import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.cash.app/network/v1/refunds") .header("Content-Type", "application/json") .body("{\n \"idempotency_key\": \"178f2318-a335-4be2-9792-6259a8887874\",\n \"refund\": {\n \"amount\": 100,\n \"currency\": \"USD\",\n \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n \"payment_id\": \"PWC_etdng09kyyqf5zr583v8xcs2k\",\n \"capture\": true,\n \"reference_id\": \"external-id\",\n \"metadata\": {\n \"key\": \"value\"\n }\n }\n}") .asString(); ``` ```php Create a $1 (USD) Refund (with metadata) request('POST', 'https://api.cash.app/network/v1/refunds', [ 'body' => '{ "idempotency_key": "178f2318-a335-4be2-9792-6259a8887874", "refund": { "amount": 100, "currency": "USD", "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x", "payment_id": "PWC_etdng09kyyqf5zr583v8xcs2k", "capture": true, "reference_id": "external-id", "metadata": { "key": "value" } } }', 'headers' => [ 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Create a $1 (USD) Refund (with metadata) using RestSharp; var client = new RestClient("https://api.cash.app/network/v1/refunds"); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"idempotency_key\": \"178f2318-a335-4be2-9792-6259a8887874\",\n \"refund\": {\n \"amount\": 100,\n \"currency\": \"USD\",\n \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n \"payment_id\": \"PWC_etdng09kyyqf5zr583v8xcs2k\",\n \"capture\": true,\n \"reference_id\": \"external-id\",\n \"metadata\": {\n \"key\": \"value\"\n }\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Create a $1 (USD) Refund (with metadata) import Foundation let headers = ["Content-Type": "application/json"] let parameters = [ "idempotency_key": "178f2318-a335-4be2-9792-6259a8887874", "refund": [ "amount": 100, "currency": "USD", "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x", "payment_id": "PWC_etdng09kyyqf5zr583v8xcs2k", "capture": true, "reference_id": "external-id", "metadata": ["key": "value"] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/refunds")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```