> 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 payout POST https://api.cash.app/network/v1/payouts Content-Type: application/json Payouts is an **early access** feature. We're actively improving this API based on your feedback. Early access features come with some caveats: * May evolve rapidly, requiring integration updates * Not subject to our 10 year version support policy * Not subject to SLAs (unless specified in a contract) Creates a payout to a customer. A payout allows a merchant to send money to a customer's Cash App account. **This endpoint is not rate-limited.** Scopes: `PAYOUTS_WRITE` Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/create-payout ## 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). - `payout` (CreatePayoutRequestPayout, required) — Data about the payout to create. ## Response ### 201 Created - `payout` (Payout, optional) ## Errors ### 400 Create Payout Request Bad Request Error Bad Request If a `PAYOUT_DECLINE_*` error is returned, the payout will still be created, but with a `DECLINED` status. This payout will then appear in the response payload. **`PAYOUT_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 taking the payout again. All other errors will not consume grants. - `errors` (list of Error, required) — A list of errors indicating why the request failed. Min number of items: `1` - `payout` (Payout, optional) ## Types ### CreatePayoutRequestPayout Data about the payout to create. - `amount` (integer, required) — The amount of money to pay the customer, in the lowest denomination of currency for the payout. 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 making the payout. Min length: `1` Max length: `128` - `grant_id` (string, required) — A grant ID from the Customer Request API that indicates permission to make the payout. Min length: `1` Max length: `256` - `purpose` (enum, required) — The purpose or intent of the payout. - Allowed values: `SERVICES`, `EARNED_WAGE_ACCESS` - `capture` (boolean, required, default: true) — Whether or not to automatically capture the payout once it's created. Default: `true` - `note` (string, required) — A note about the payout that will be shown to the customer. Min length: `1` Max length: `1024` - `reference_id` (string, optional) — A user-defined identifier for this payout, typically used to associate the payout 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. ### Payout - `payout_id` (string, required) — Unique identifier for this payout issued by Cash App. Min length: `1` Max length: `128` - `grant_id` (string, required) — ID of the grant used to create this payout. Min length: `1` Max length: `256` - `amount` (integer, required) — The amount of money to pay, in the lowest denomination of currency on the payout. This is the _original_ amount authorized when the payout was created. 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` - `status` (enum, required) — The step of the payout processing lifecycle that this payout is currently at. - `CAPTURED` - Payout is captured and funds have been sent - `DECLINED` - Payout was declined - `AUTHORIZED` - Payout is authorized but not yet captured - `INITIATED` - Payout has been created but no money movement has happened yet - `VOIDED` - Payout authorization was released and funds were not sent - Allowed values: `CAPTURED`, `DECLINED`, `AUTHORIZED`, `INITIATED`, `VOIDED` - `merchant_id` (string, required) — ID of the merchant that made this payout. Min length: `1` Max length: `128` - `purpose` (enum, required) — The purpose or intent of the payout. - Allowed values: `SERVICES`, `EARNED_WAGE_ACCESS` - `customer_id` (string, optional) — ID of the customer that received this payout. Min length: `1` Max length: `128` - `authorized_amount` (integer, optional) — The amount of money on this payout that has been authorized. The amount will be in the lowest denomination of the currency on the payout. Min value: `0` - `captured_amount` (integer, optional) — The amount of money on this payout that has been allocated for settlement. The amount will be in the lowest denomination of the currency on the payout. Min value: `0` - `declined_amount` (integer, optional) — The amount of money on this payout that was declined. The amount will be in the lowest denomination of the currency on the payout. Min value: `0` - `voided_amount` (integer, optional) — The amount of money on this payout that is no longer authorized and has been released. The amount will be in the lowest denomination of the currency on the payout. Min value: `0` - `reference_id` (string, optional) — A user-defined identifier for this payout, typically used to associate the payout with a record in an external system. Min length: `1` Max length: `1024` - `fee_amount` (double, optional) — The total fee amount that was charged to the merchant for processing this payout. - `fee_rate` (FeeRate, optional) — The breakdown of the fee that was charged to the merchant for processing this payout. - `note` (string, optional) — A note about the payout that will be shown to the customer. 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 payout 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` ### FeeRate A fee rate contains the components of a fee charged by Cash App to partners for a given payment. - `basis_points` (integer, optional) — The variable fee charged for processing the payment expressed as 1/100th of a percentage. - `fixed_amount` (integer, optional) — The amount charged for processing the payment, in the lowest denomination of currency on the payment. **Note: The currency for the fee is found on the fee plan.** ## Examples **Request** ```json { "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19", "payout": { "amount": 1500, "currency": "USD", "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x", "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50", "purpose": "SERVICES", "capture": true, "note": "Payment for consulting work completed in January" } } ``` **Response** ```json { "payout": { "payout_id": "CAPO_4nn21zy6t0v2yhqg5bvhk7xkq", "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50", "amount": 1500, "currency": "USD", "status": "CAPTURED", "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x", "purpose": "SERVICES", "customer_id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY", "authorized_amount": 1500, "captured_amount": 1500, "declined_amount": 0, "voided_amount": 0 } } ``` **SDK Code** ```python Captured payout import requests url = "https://api.cash.app/network/v1/payouts" payload = { "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19", "payout": { "amount": 1500, "currency": "USD", "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x", "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50", "purpose": "SERVICES", "capture": True, "note": "Payment for consulting work completed in January" } } headers = {"Content-Type": "application/json"} response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Captured payout const url = 'https://api.cash.app/network/v1/payouts'; const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","payout":{"amount":1500,"currency":"USD","merchant_id":"MMI_4vxs5egfk7hmta3qx2h6rp91x","grant_id":"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50","purpose":"SERVICES","capture":true,"note":"Payment for consulting work completed in January"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Captured payout package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.cash.app/network/v1/payouts" payload := strings.NewReader("{\n \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n \"payout\": {\n \"amount\": 1500,\n \"currency\": \"USD\",\n \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n \"grant_id\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\",\n \"purpose\": \"SERVICES\",\n \"capture\": true,\n \"note\": \"Payment for consulting work completed in January\"\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 Captured payout require 'uri' require 'net/http' url = URI("https://api.cash.app/network/v1/payouts") 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\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n \"payout\": {\n \"amount\": 1500,\n \"currency\": \"USD\",\n \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n \"grant_id\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\",\n \"purpose\": \"SERVICES\",\n \"capture\": true,\n \"note\": \"Payment for consulting work completed in January\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java Captured payout import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.cash.app/network/v1/payouts") .header("Content-Type", "application/json") .body("{\n \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n \"payout\": {\n \"amount\": 1500,\n \"currency\": \"USD\",\n \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n \"grant_id\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\",\n \"purpose\": \"SERVICES\",\n \"capture\": true,\n \"note\": \"Payment for consulting work completed in January\"\n }\n}") .asString(); ``` ```php Captured payout request('POST', 'https://api.cash.app/network/v1/payouts', [ 'body' => '{ "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19", "payout": { "amount": 1500, "currency": "USD", "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x", "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50", "purpose": "SERVICES", "capture": true, "note": "Payment for consulting work completed in January" } }', 'headers' => [ 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Captured payout using RestSharp; var client = new RestClient("https://api.cash.app/network/v1/payouts"); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n \"payout\": {\n \"amount\": 1500,\n \"currency\": \"USD\",\n \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n \"grant_id\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\",\n \"purpose\": \"SERVICES\",\n \"capture\": true,\n \"note\": \"Payment for consulting work completed in January\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Captured payout import Foundation let headers = ["Content-Type": "application/json"] let parameters = [ "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19", "payout": [ "amount": 1500, "currency": "USD", "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x", "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50", "purpose": "SERVICES", "capture": true, "note": "Payment for consulting work completed in January" ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/payouts")! 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() ```