Cash App Pay Integration

intent

this skill integrates cash app pay into your payment system to accept u.s.-only payments directly from cash app balances, linked bank accounts, or cards. use this when you need a checkout solution optimized for mobile-first commerce with no manual card entry friction. cash app is the number one personal finance app in the u.s. by monthly active users. the skill covers both front-end ui (pay kit sdk for web, ios, android) and back-end apis (network api for payments, customer request api for authentication, management api for credential and webhook lifecycle).

inputs

environment variables / secrets:

• CASHAPP_CLIENT_ID (string, required): client id for customer request api. obtained from cash app partner engineering during onboarding.
• CASHAPP_API_KEY (string, required): api key for network api and management api. never expose this client-side. obtained from cash app partner engineering during onboarding.

external connections:

• cash app partner engineering team (required): must contact them to confirm your integration path (seller vs psp), obtain sandbox credentials (separate from production), and get approval for production onboarding.
• sftp server (settlement/dispute reporting): cash app uploads daily reconciliation and dispute reports to a psp-hosted sftp server. requires sftp credentials and server configuration.
• webhook delivery endpoint (optional but recommended): your server must expose an https endpoint to receive real-time customer request state change notifications.

context / existing data required:

• merchant_id (string): cash app merchant id created via the network api brands and merchants endpoints. required for all payments.
• brand_id (string): cash app brand id created via the network api. required to create merchants.
• grant_id (string): authorization grant from an approved customer request. required to create a payment.
• customer_request_id (string): id of the customer request. used to poll for approval status or subscribe to webhook events.

device/platform context:

• device type (desktop, mobile app, or in-person pos): determines which channel and auth flow to use (qr code vs redirect vs pos device).

procedure

step 1: set up brand and merchant (one-time)

input: your store name, address, mcc category code (e.g. 5500 for general merchandise), reference id (your internal identifier).

1. call POST /network/v1/brands with your brand name, reference id, and idempotency key (uuid).
2. parse the response and save the brand_id.
3. call POST /network/v1/merchants with the brand_id, merchant name, full address, country (us only), currency (usd), category, reference id, and idempotency key.
4. parse the response and save the merchant_id.

output: brand_id (string), merchant_id (string). store these in your database.

note: idempotency keys prevent duplicate brand/merchant creation if you retry. always use a new uuid per request.

step 2: create a customer request (per transaction)

input: merchant_id, payment amount (integer, cents), channel (online, in_app, or in_person), action type (one_time_payment, on_file_payment, or link_account), reference id (your order id), idempotency key (uuid).

1. call POST /customer-request/v1/requests with authorization header Client {{client_id}} (not the api key).
2. include actions array with type, amount, currency, scope_id (merchant_id).
3. include channel (exactly one: online, in_app, or in_person).
4. parse response and extract customer_request_id and auth_flow_triggers object (contains qr_code_url, mobile_url, desktop_url).
5. if device is desktop, display the qr code from auth_flow_triggers.qr_code_url (refreshes every 30 seconds, expires every 60 seconds).
6. if device is mobile, redirect to auth_flow_triggers.mobile_url.
7. if device is in-person pos, use the auth_flow_triggers.in_person_url or display on pos terminal.

output: customer_request_id (string), auth_flow_triggers object (qr_code_url, mobile_url, desktop_url, expires_at, refreshes_at).

note: qr codes rotate every 30 seconds and expire every 60 seconds. always fetch fresh from polling or webhook to avoid expired codes. do not cache qr code urls.

step 3: poll or subscribe for customer approval

input: customer_request_id.

option a (polling):

1. call GET /customer-request/v1/requests/{{customer_request_id}} every 1 second (or subscribe to webhook instead).
2. check the state field in the response.
3. if state is approved, extract grant_id from the grants array and go to step 4.
4. if state is declined or expired, show error to customer and return to step 2.
5. if state is still pending, continue polling (timeout after 10 minutes).

option b (webhooks):

1. subscribe to customer_request.state.updated events via management api (see resources).
2. when webhook fires with state approved, extract grant_id from payload and go to step 4.
3. if state is declined or expired, handle error.

output: grant_id (string, from grants[0].grant_id), state (string: approved, declined, expired, or pending).

note: polling requires 1 request per second and may hit rate limits. webhooks are recommended for production.

step 4: create a payment (server-side only)

input: merchant_id, grant_id, amount (integer, cents), currency (usd), idempotency key (uuid), capture flag (true for auth-and-capture, false for auth-only), reference id (order id).

1. construct payment body with merchant_id, grant_id, amount, currency, capture, reference_id, and idempotency_key.
2. call POST /network/v1/payments with headers:
   • Authorization: {{api_creds}} (use CASHAPP_API_KEY)
   • Content-Type: application/json
   • Accept: application/json
   • X-Region: PDX
   • X-Signature: <computed_signature> (production only; sandbox: sandbox:skip-signature-check)
3. parse response and extract payment_id, state, amount, created_at.
4. if state is approved, payment succeeded.
5. if state is declined, return decline reason to customer and return to step 2.
6. if state is error, log and retry with new idempotency key after 5 seconds (one retry max).

output: payment_id (string), state (string: approved, declined, error, voided, or captured), amount (integer), created_at (iso8601 timestamp).

note: all network api requests must be signed in production. signatures prevent tampering. in sandbox, bypass with X-Signature: sandbox:skip-signature-check. see cash app docs for signature algorithm details.

step 5 (optional): capture auth-only payment

input: payment_id (from step 4, if capture was false).

1. call POST /network/v1/payments/{{payment_id}}/capture with idempotency key and signature header.
2. parse response and check state (should be captured).

output: payment_id, state (captured).

step 6 (optional): void or refund

to void a payment (before capture or after):

1. call POST /network/v1/payments/{{payment_id}}/void with idempotency key and signature.
2. parse response. state should be voided.

to refund (after capture):

1. call POST /network/v1/refunds with payment_id, amount, currency, reference_id, and idempotency key.
2. parse response and extract refund_id, state.

output: payment_id or refund_id, state (voided or refund_approved).

step 7 (optional): handle disputes

input: payment_id with a dispute attached (returned in payment details or via daily dispute sftp report).

1. call GET /network/v1/disputes to list active disputes.
2. for each dispute, extract dispute_id, reason (e.g. cd10, fr10), amount, state (open, processing, won, lost).
3. to submit text evidence, call POST /network/v1/disputes/{{dispute_id}}/evidence with evidence_type, text, and metadata.
4. to submit file evidence (e.g. invoice pdf), call the same endpoint with evidence_type, file_url, and metadata.
5. parse response. dispute state should be processing after submission.

output: dispute_id, state (processing, won, lost, partially_won).

decision points

if device is desktop (web checkout):

• display qr code from auth_flow_triggers.qr_code_url. customer scans with cash app. customer approves in cash app. go to step 3 (polling or webhook).

if device is mobile (app or mobile web):

• redirect to auth_flow_triggers.mobile_url. cash app opens. customer approves. cash app redirects back to your app. go to step 3.

if device is in-person (pos terminal):

• display qr code on pos screen or send to pos device. customer scans. go to step 3.

if customer request state is approved:

• extract grant_id and proceed to step 4 (create payment).

if customer request state is declined or expired:

• show error message to customer. return to step 2 (create new customer request). do not retry the expired request.

if payment state is approved:

• payment succeeded. return success to customer. store payment_id for reconciliation.

if payment state is declined:

• payment failed. return decline reason to customer (e.g. insufficient funds, risk, compliance). return to step 2 (create new customer request). do not retry the same grant_id.

if payment state is error (connection error or timeout):

• retry step 4 once after 5 seconds with a new idempotency key. if it fails again, escalate to cash app support.

if using auth-only (capture=false):

• store payment_id. proceed to step 5 later (capture) when order is ready to ship or fulfill.

if payment is disputed:

• check GET /network/v1/disputes or monitor sftp dispute report. decide whether to submit evidence (step 7) or accept the chargeback. evidence can improve win rate.

if integrating as a psp (multi-merchant platform):

• create separate brand + merchant per seller. use management api to create scoped api keys with least-privilege access for each seller microservice.

if integrating as a seller (direct merchant):

• create one brand + merchant. use single api key with full access.

if rate limited:

• cash app api rate limits are enforced per api key. if you receive 429 response, backoff exponentially (start with 2 seconds, double each retry, max 60 seconds). max 3 retries.

if api credentials expire or are rotated:

• use management api to rotate credentials without downtime. cache new credentials in memory. old credentials remain valid for 30 days (grace period).

if webhook delivery fails:

• cash app retries webhook delivery up to 5 times over 24 hours. acknowledge delivery with http 200. if your server is down, re-poll customer request status manually on recovery.

if settling disputes in sandbox:

• use magic metadata values (e.g. {"sandbox:set_dispute_state": "WON"}) to transition dispute state for testing without waiting for manual review.

output contract

success criteria:

• step 1 output: brand_id and merchant_id stored in database. merchant is active and ready to receive payments.
• step 2 output: customer_request_id and auth_flow_triggers returned. qr code or redirect url is valid and displays to customer.
• step 3 output: grant_id extracted from approved request. grant is valid and not consumed, expired, or revoked.
• step 4 output: payment_id created. payment state is approved and amount is deducted from customer's cash app balance (or linked account). payment_id is idempotent (retrying with same idempotency key returns same payment_id).
• step 5 output (if used): payment state transitions from approved to captured.
• step 6 output (if used): refund_id created. refund state is refund_approved. amount is credited back to customer within 1-3 business days.
• step 7 output (if used): dispute state transitions to processing after evidence submission.

data format (json): all responses are json objects with root keys: id, created_at, type, and type-specific fields (e.g. payment → amount, currency, merchant_id, state).

file locations / storage:

• brand_id and merchant_id: store in your app database (do not hardcode).
• api credentials: store in secure vault (env vars, secrets manager, kms). never commit to git.
• payment_id, refund_id, dispute_id: log to transaction table with timestamps and states for reconciliation.
• settlement/dispute reports: fetch daily from sftp and store in data warehouse or accounting system.

idempotency: all write operations (brand, merchant, payment, refund, void) are idempotent. retrying with the same idempotency_key returns the same resource without creating duplicates.

outcome signal

the user knows the skill worked when:

1. brand and merchant created: POST /network/v1/brands and POST /network/v1/merchants both return http 201 with brand_id and merchant_id in the response. you can see the merchant in cash app partner dashboard.

2. customer request created: POST /customer-request/v1/requests returns http 201 with a valid qr code url or mobile redirect url. customer can scan or tap without errors.

3. customer approved: polling GET /customer-request/v1/requests/{{id}} returns state approved with a valid grant_id. webhook event customer_request.state.updated fires (if subscribed).

4. payment created: POST /network/v1/payments returns http 201 with payment state approved. amount appears in your settlement report 24 hours later. customer sees the charge in their cash app transaction history.

5. payment captured (if auth-only): POST /network/v1/payments/{{id}}/capture returns http 200 with state captured. amount is now final and will settle.

6. refund created: POST /network/v1/refunds returns http 201 with state refund_approved. customer sees credit in cash app within 1-3 business days.

7. dispute evidence submitted: POST /network/v1/disputes/{{id}}/evidence returns http 200. dispute state transitions to processing. cash app reviews and resolves within 7-10 days.

8. settlement received: daily sftp report shows net settlement amount (gross payments minus refunds and disputes) deposited to your bank account. reconciliation matches your transaction log.

---

sandbox testing

in sandbox, all requests behave identically to production except signatures are optional. set X-Signature: sandbox:skip-signature-check and credentials are separate from production.

magic payment amounts (trigger specific outcomes in sandbox):

amount (cents)	result
6670	connection error returned, but payment still created (tests error handling)
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-8804, 8811-8812, 8821-8823, 8901	payment created plus dispute with specific reason code (tests dispute flow)

magic grant ids (simulate customer request outcomes):

grant id	result
GRG_sandbox:active	payment succeeds
GRG_sandbox:consumed	decline: grant already used
GRG_sandbox:expired	decline: grant expired
GRG_sandbox:missing	decline: grant not found
GRG_sandbox:revoked	decline: grant revoked by customer

magic merchant ids (simulate merchant errors):

merchant id	result
MMI_sandbox:disabled	error: merchant is disabled
MMI_sandbox:pending	error: merchant onboarding pending
MMI_sandbox:missing	error: merchant not found

magic dispute metadata (transition dispute state in sandbox):

metadata key	value	result
sandbox:set_dispute_state	PROCESSING	dispute moves to processing state
sandbox:set_dispute_state	WON	dispute resolved, you won
sandbox:set_dispute_state	PARTIALLY_WON	dispute partially resolved in your favor
sandbox:set_dispute_state	LOST	dispute lost

---

pay kit sdk (front-end ui)

pay kit is cash app's sdk for embedding payment ui without building custom auth flows. it handles customer request creation and polling under the hood.

platforms:

• web: javascript sdk. displays qr code on desktop, redirects on mobile.
• ios: native sdk. integrates with app checkout.
• android: native sdk. integrates with app checkout.

behavior:

• on desktop: renders qr code. customer scans with cash app. cash app opens, customer approves, qr code clears.
• on mobile: redirects to cash app. customer approves. redirects back to your app.

advanced mode: pay kit also supports fine-grained control over when auth flow starts (e.g. "show button, on click open flow"). see cash app pay kit docs for implementation.

after customer approves via pay kit, your backend receives the grant_id and proceeds to step 4 (create payment).

---

edge cases and constraints

rate limits:

• cash app enforces rate limits per api key: ~100 requests per second. if you hit 429 (too many requests), backoff exponentially (2s, 4s, 8s, max 60s). do not hammer the api in a loop.

auth expiry:

• api credentials are valid indefinitely but can be rotated. use management api to rotate without downtime. old credentials remain valid for 30 days after rotation.

empty result sets:

• GET /network/v1/disputes may return empty list if no active disputes. this is normal.
• GET /network/v1/payments/{{id}} with invalid payment_id returns 404. always validate payment_id before lookup.

network timeouts:

• cash app api is regional (pdx). timeouts are rare but can occur. implement exponential backoff (start 1s, max 60s, 3 retries). do not retry more than 3 times (idempotency key prevents duplicates, but excessive retries waste resources).

qr code rotation and expiry:

• qr codes refresh every 30 seconds (refreshes_at timestamp in polling response). qr codes expire every 60 seconds (expires_at timestamp). always fetch fresh from polling, do not cache urls.

declined or expired grants:

• if customer declines or request expires (60s idle), grant_id becomes invalid. do not retry with the same grant_id. create a new customer request (step 2).

signature verification in production:

• all network api and management api requests must be signed with X-Signature header in production. signing algorithm is hmac-sha256. see cash app docs for details. failure to sign results in 401 unauthorized.

idempotency key uniqueness:

• reusing the same idempotency key across different requests (e.g. different amounts) does not create duplicates but returns the original resource. always use a new uuid per logical request.

u.s. only:

• cash app pay is available in the u.s. only. merchant and customer must be in u.s. currency is usd. do not attempt international transactions.

settlement timing:

• payments settle daily to your bank account, typically next business day. dispute deductions are applied to the settlement (net settlement model). watch for negative settlements if disputes exceed payments.

webhook retry logic:

• cash app retries failed webhook deliveries up to 5 times over 24 hours with exponential backoff. always respond with http 200 to acknowledge. if your server is down, manually re-poll on recovery.

---

resources

• cash app pay developer docs
• network api reference
• pay kit web guide
• pay kit ios guide
• pay kit android guide
• cash app pay status page
• postman collection
• glossary

---

note: cash app pay is a block, inc. product (formerly square). it is not affiliated with implexa or clawhub. partner onboarding requires approval from cash app partner engineering team. sandbox credentials are separate from production. never use production credentials in sandbox or vice versa.