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.

Actions (specify one or more per request):

Channels (specify exactly one):

Authorization flow:

1. Create a customer request → receive auth_flow_triggers (QR code URL, mobile URL, desktop URL)
2. Customer scans QR code (desktop) or is redirected to Cash App (mobile) to approve
3. Poll the request (1x/sec recommended) or use webhooks (customer_request.state.updated)
4. When state = approved, save the grant_id from the grants array
5. 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).

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.

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.

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.

Magic Values (Payment Amounts)

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

Magic Grant IDs

Magic Merchant IDs

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):

Integration Paths

Resources

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.