> 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 incremental authorization POST https://api.cash.app/network/v1/payments/{payment_id}/authorizations Content-Type: application/json Creates an authorization update for a payment. The authorization amount must be greater than or equal to the current authorized amount. Use this endpoint for incremental authorization instead of overcapturing using the Capture payment endpoint. By creating additional payment authorizations exceeding the current authorized amount, you can request additional funds without risking the original amount being declined. **This endpoint is not rate limited.** Scopes: `PAYMENTS_WRITE` Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/create-payment-authorization ## Servers - `https://api.cash.app/network/v1` (Production, default) - `https://sandbox.api.cash.app/network/v1` (Sandbox) ## Request ### Path parameters - `payment_id` (string, required) — ID of the payment to create an authorization for. ### 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). - `authorization` (CreatePaymentAuthorizationRequestAuthorization, required) — Details about the authorization to create. ## Response ### 201 Created - `authorization` (Authorization, required) — Represents an authorization update for a payment ## Errors ### 400 Create Payment Authorization Request Bad Request Error Bad Request If a AUTHORIZATION_DECLINE_* error is returned, the authorization will still be created, but with a DECLINED status. This authorization will then appear in the response payload. - `errors` (list of Error, required) — A list of errors indicating why the request failed. Min number of items: `1` - `authorization` (Authorization, optional) — Represents an authorization update for a payment ### 404 Create Payment Authorization Request Not Found Error Not Found - `errors` (list of Error, required) — A list of errors that occurred while processing the request. Min number of items: `1` ## Types ### CreatePaymentAuthorizationRequestAuthorization Details about the authorization to create. - `amount` (integer, required) — The updated total amount of money to collect from the customer, in the lowest denomination of currency for the payment. This value must be greater than or equal to the current authorized amount - `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` - `reference_id` (string, optional) — A user-defined identifier for this authorization, typically used to associate the authorization 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. ### Authorization Represents an authorization update for a payment - `id` (string, required) — Unique identifier for this authorization issued by Cash App. Min length: 1 character Max length: 128 characters - `amount` (integer, required) — Total authorized amount after this authorization was processed, in the lowest denomination of currency on the payment. - `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 authorization processing lifecycle that this authorization is currently at. Allowed values: - AUTHORIZED - DECLINED - Allowed values: `AUTHORIZED`, `DECLINED` - `created_at` (datetime, required) — When this authorization was created, in RFC 3339 format (UTC). - `payment_id` (string, required) — ID of the payment associated with this authorization - `previous_amount` (integer, required) — Total authorized amount before this authorization was requested - `reference_id` (string, optional) — A user-defined identifier for this authorization, typically used to associate the authorization 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 authorization was declined, it 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": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19", "authorization": { "amount": 100, "currency": "USD" } } ``` **Response** ```json { "authorization": { "id": "id", "amount": 1, "currency": "USD", "status": "AUTHORIZED", "created_at": "2024-01-15T09:30:00Z", "payment_id": "payment_id", "previous_amount": 1, "reference_id": "reference_id", "metadata": { "my-meta": "meta-value" }, "decline_errors": [ { "category": "INVALID_REQUEST_ERROR", "code": "MISSING_REQUIRED_FIELD", "detail": "Missing required parameter.", "field": "field_a[2].field_b" } ] } } ``` **SDK Code** ```python import requests url = "https://api.cash.app/network/v1/payments/PWC_4nn21zy6t0v2yhqg5bvhk7xkq/authorizations" payload = { "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19", "authorization": { "amount": 100, "currency": "USD" } } headers = {"Content-Type": "application/json"} response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.cash.app/network/v1/payments/PWC_4nn21zy6t0v2yhqg5bvhk7xkq/authorizations'; const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","authorization":{"amount":100,"currency":"USD"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.cash.app/network/v1/payments/PWC_4nn21zy6t0v2yhqg5bvhk7xkq/authorizations" payload := strings.NewReader("{\n \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n \"authorization\": {\n \"amount\": 100,\n \"currency\": \"USD\"\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 require 'uri' require 'net/http' url = URI("https://api.cash.app/network/v1/payments/PWC_4nn21zy6t0v2yhqg5bvhk7xkq/authorizations") 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 \"authorization\": {\n \"amount\": 100,\n \"currency\": \"USD\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.cash.app/network/v1/payments/PWC_4nn21zy6t0v2yhqg5bvhk7xkq/authorizations") .header("Content-Type", "application/json") .body("{\n \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n \"authorization\": {\n \"amount\": 100,\n \"currency\": \"USD\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api.cash.app/network/v1/payments/PWC_4nn21zy6t0v2yhqg5bvhk7xkq/authorizations', [ 'body' => '{ "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19", "authorization": { "amount": 100, "currency": "USD" } }', 'headers' => [ 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.cash.app/network/v1/payments/PWC_4nn21zy6t0v2yhqg5bvhk7xkq/authorizations"); 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 \"authorization\": {\n \"amount\": 100,\n \"currency\": \"USD\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Content-Type": "application/json"] let parameters = [ "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19", "authorization": [ "amount": 100, "currency": "USD" ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/payments/PWC_4nn21zy6t0v2yhqg5bvhk7xkq/authorizations")! 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() ```