Cash App Pay — Accept Payments from Cash App

Cash App Pay is a checkout solution by Block, Inc. that lets U.S. consumers pay directly from their Cash App balance, linked bank account, or card. It eliminates manual card entry and is optimized for mobile-first commerce.

Cash App is the #1 personal finance app in the U.S. by monthly active users. Cash App Pay is available for e-commerce (web and mobile) and point-of-sale (POS) integrations.

Developer Docs: developers.cash.app Production Base URL: https://api.cash.app Sandbox Base URL: https://sandbox.api.cash.app

Architecture Overview

Cash App Pay integrations have two components:

┌─────────────────────────────────────────────────┐
│                   FRONT END                      │
│  Pay Kit SDK (Web / iOS / Android)               │
│  - Renders QR code (desktop) or redirect (mobile)│
│  - Handles customer authentication flow          │
│  - Uses Customer Request API under the hood      │
└───────────────────────┬─────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│                   BACK END                       │
│  Network API     — Payments, merchants, disputes │
│  Management API  — Credentials, webhooks, keys   │
│  Batch Reporting — Settlements, dispute reports   │
│  (All server-side only — never call from browser)│
└─────────────────────────────────────────────────┘

APIs

Customer Request API (Client-side)

Handles linking a customer to a merchant. This is what Pay Kit uses under the hood. Can also be called directly for API-only integrations.

Method	Endpoint	Description
POST	`/customer-request/v1/requests`	Create a customer request
GET	`/customer-request/v1/requests/{id}`	Retrieve a customer request (poll for status)

Actions (specify one or more per request):

Action	Description
`ONE_TIME_PAYMENT`	Single payment
`ON_FILE_PAYMENT`	Store payment method for future charges
`LINK_ACCOUNT`	Link customer's Cash App account

Channels (specify exactly one):

Channel	Use Case
`ONLINE`	E-commerce web checkout
`IN_APP`	Mobile app checkout
`IN_PERSON`	Point-of-sale devices

Authorization flow:

Create a customer request → receive auth_flow_triggers (QR code URL, mobile URL, desktop URL)
Customer scans QR code (desktop) or is redirected to Cash App (mobile) to approve
Poll the request (1x/sec recommended) or use webhooks (customer_request.state.updated)
When state = approved, save the grant_id from the grants array
Use the grant_id to create a payment via the Network API

QR codes rotate every 30 seconds and expire every 60 seconds — always fetch the latest from the polling response.

Network API (Server-side)

Server-to-server API for core payment operations. All requests must be signed (see Signatures section below).

Method	Endpoint	Description
POST	`/network/v1/brands`	Create a brand
GET	`/network/v1/brands`	List brands
POST	`/network/v1/merchants`	Create a merchant under a brand
GET	`/network/v1/merchants/{id}`	Retrieve a merchant
POST	`/network/v1/payments`	Create a payment
GET	`/network/v1/payments/{id}`	Retrieve a payment
POST	`/network/v1/payments/{id}/void`	Void a payment
POST	`/network/v1/payments/{id}/capture`	Capture a payment
POST	`/network/v1/refunds`	Create a refund
GET	`/network/v1/refunds/{id}`	Retrieve a refund
POST	`/network/v1/refunds/{id}/void`	Void a refund
GET	`/network/v1/disputes`	List disputes
POST	`/network/v1/disputes/{id}/evidence`	Submit dispute evidence (text or file)

Required headers:

Authorization: <api_creds>
Content-Type: application/json
Accept: application/json
X-Region: PDX
X-Signature: <signature> (or sandbox:skip-signature-check in sandbox)

Idempotency: All write operations require an idempotency_key (UUID) in the request body to prevent duplicate operations.

Management API (Server-side)

Automates integration management:

Secure credential rotation
Webhook subscription management
Creating scoped API keys (for microservices with least-privilege access)

Quick Start — API Integration

Step 1: Create a Brand and Merchant

# Create a brand
curl -X POST https://sandbox.api.cash.app/network/v1/brands \
  -H "Authorization: {{api_creds}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Region: PDX" \
  -d '{
    "brand": {
      "name": "My Store",
      "reference_id": "external-id"
    },
    "idempotency_key": "unique-uuid-here"
  }'

# Create a merchant under the brand
curl -X POST https://sandbox.api.cash.app/network/v1/merchants \
  -H "Authorization: {{api_creds}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Region: PDX" \
  -d '{
    "merchant": {
      "name": "My Store - Main",
      "brand_id": "BRAND_xxxxx",
      "address": {
        "address_line_1": "1 Market Street",
        "locality": "San Francisco",
        "administrative_district_level_1": "CA",
        "postal_code": "94105",
        "country": "US"
      },
      "country": "US",
      "currency": "USD",
      "category": "5500",
      "reference_id": "external-id"
    },
    "idempotency_key": "unique-uuid-here"
  }'

Step 2: Create a Customer Request

curl -X POST https://sandbox.api.cash.app/customer-request/v1/requests \
  -H "Authorization: Client {{client_id}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "request": {
      "actions": [
        {
          "type": "ONE_TIME_PAYMENT",
          "amount": 1234,
          "currency": "USD",
          "scope_id": "{{merchant_id}}"
        }
      ],
      "channel": "ONLINE",
      "reference_id": "order-12345"
    },
    "idempotency_key": "unique-uuid-here"
  }'

The response contains auth_flow_triggers with QR code URL, mobile URL, and desktop URL. Poll the retrieve endpoint until state = approved, then save the grant_id.

Step 3: Create a Payment

curl -X POST https://sandbox.api.cash.app/network/v1/payments \
  -H "Authorization: {{api_creds}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Region: PDX" \
  -d '{
    "payment": {
      "amount": 1234,
      "currency": "USD",
      "merchant_id": "{{merchant_id}}",
      "grant_id": "{{grant_id}}",
      "capture": true,
      "reference_id": "order-12345"
    },
    "idempotency_key": "unique-uuid-here"
  }'

Set "capture": false for auth-only, then capture later via the capture endpoint.

Pay Kit SDK (Front End)

Pay Kit is Cash App's JavaScript SDK for embedding payment UI. It handles the Customer Request flow automatically.

Platform	Resources
Web	Pay Kit Web Guide
iOS	Pay Kit iOS Guide
Android	Pay Kit Android Guide

Pay Kit adapts to the user's device:

Desktop → Displays a QR code for scanning with Cash App
Mobile → Redirects to Cash App for authentication, then back to merchant

For advanced control over when and how the authorization flow starts, use Pay Kit's advanced controls mode.

Webhooks

Subscribe to webhook events for real-time updates instead of polling.

Event	Trigger
`customer_request.state.updated`	Customer request state changes (approved, declined, etc.)

Webhook subscriptions are managed through the Management API. There is no webhook event for QR code rotation — use polling or check the refreshes_at timestamp to fetch the latest QR code.

Sandbox

Cash App provides a full sandbox environment for testing without moving real money.

Item	Value
Sandbox host	`sandbox.api.cash.app`
Sandbox App	Available for testing customer approval flows
Sandbox Web	Web-based approval simulator
Credentials	Separate from production — obtain from Cash App Partner Engineering
Signature bypass	Set `X-Signature: sandbox:skip-signature-check`
Backwards compatibility	5-year guarantee on sandbox magic values

Magic Values (Payment Amounts)

Use these amounts in the amount field to trigger specific outcomes:

Amount	Result
`6670`	Connection error (HTTP error returned, payment still created)
`7770`	Decline: compliance failure
`7771`	Decline: insufficient funds
`7772`	Decline: other
`7773`	Decline: risk
`7774`	Decline: amount too large
`7775`	Decline: amount too small
`8801`	Creates payment + dispute (reason CD10)
`8802`	Creates payment + dispute (reason CD11)
`8803`	Creates payment + dispute (reason CD12)
`8804`	Creates payment + dispute (reason CD13)
`8811`	Creates payment + dispute (reason FR10 — fraud)
`8812`	Creates payment + dispute (reason FR11 — fraud)
`8821`–`8823`	Creates payment + dispute (PE10–PE12 — processing error)
`8901`	Creates payment + dispute with differing disputed amount

Magic Grant IDs

Grant ID	Result
`GRG_sandbox:active`	Payment created successfully
`GRG_sandbox:consumed`	Decline: grant consumed
`GRG_sandbox:expired`	Decline: grant expired
`GRG_sandbox:missing`	Decline: grant not found
`GRG_sandbox:revoked`	Decline: grant revoked

Magic Merchant IDs

Merchant ID	Result
`MMI_sandbox:disabled`	Error: merchant disabled
`MMI_sandbox:pending`	Error: merchant pending
`MMI_sandbox:missing`	Error: merchant not found

Request Signatures

All Network API and Management API requests must be signed in production. Signatures are provided via the X-Signature header.

In sandbox, bypass signing by setting:

X-Signature: sandbox:skip-signature-check

For production signing implementation details, see the Making Requests documentation.

Settlements & Disputes

Settlements

Cash App uses net settlement — refund and dispute amounts are deducted from settlement payouts. Reconciliation reports are uploaded daily via SFTP to a PSP-hosted server, regardless of whether there was payment activity.

Disputes

Dispute reports are also uploaded daily via SFTP. Use the Network API's dispute endpoints to retrieve dispute details and submit evidence (text or file-based).

Dispute evidence magic values (sandbox):

Metadata Value	Result
`{"sandbox:set_dispute_state": "PROCESSING"}`	Dispute moves to PROCESSING
`{"sandbox:set_dispute_state": "WON"}`	Dispute resolved — won
`{"sandbox:set_dispute_state": "PARTIALLY_WON"}`	Dispute resolved — partially won
`{"sandbox:set_dispute_state": "LOST"}`	Dispute resolved — lost

Integration Paths

Path	Best For	Docs
Cash App Afterpay (Sellers)	Merchants adding Cash App Pay or Afterpay to their checkout	Seller Docs
Cash App Pay Partner API (PSPs)	Payment service providers building platform-level integrations	PSP Docs

Resources

Resource	URL
Developer Documentation	developers.cash.app
API Reference (Network)	Network API Reference
Cash App Pay Status	Status Page
Brand Assets	Cash App Pay Assets
Glossary	Glossary of Terms
Postman Collection	Postman Collection

Important Notes

Cash App Pay is U.S. only. Both merchants and customers must be in the United States. Currency is USD.
All Network/Management API requests must be signed in production. Use the X-Signature header. In sandbox, set it to sandbox:skip-signature-check.
All write operations require an idempotency key. Use a unique UUID for each request to prevent duplicate charges, refunds, or merchant registrations.
QR codes rotate every 30 seconds and expire every 60 seconds. Always fetch the latest from polling responses. Do not cache QR code URLs.
Sandbox credentials are separate from production. Never use production credentials in the sandbox or vice versa.
Partner onboarding requires approval. Contact the Cash App Pay Partner Engineering team to confirm the right integration path and obtain API credentials.
Never expose API credentials client-side. The Network API and Management API are server-side only. Only the Customer Request API and Pay Kit SDK are used on the client.
Cash App Pay is a product of Block, Inc. (formerly Square, Inc.). It is not affiliated with CreditClaw.

CashClaw | Give your agent a wallet or c