API Integration Quickstart

We recommend that partners use the Pay Kit SDK to integrate with Cash App Pay.

Integrate with the Cash App Pay API

Step 1: Create a Brand and Merchant

First, create a Brand and associate a Merchant with that brand.

1. Create a Brand

   1
   curl --location 'https://sandbox.api.cash.app/network/v1/brands' \
   2
   --header 'Authorization: {{api_creds}}' \
   3
   --header 'Content-Type: application/json' \
   4
   --header 'Accept: application/json' \
   5
   --header 'X-Region: PDX' \
   6
   --data '{
   7
     "brand": {
   8
          "name": "Cash App",
   9
          "reference_id": "external-id"
   10
     },
   11
     "idempotency_key": "224841f7-31be-4bc6-b1df-e102a8fa476f"
   12
   }'

2. Create a Merchant

   1
   curl --location 'https://sandbox.api.cash.app/network/v1/merchants' \
   2
   --header 'Authorization: {{api_creds}}' \
   3
   --header 'Content-Type: application/json' \
   4
   --header 'Accept: application/json' \
   5
   --header 'X-Region: PDX' \
   6
   --data '{
   7
        "merchant": {
   8
            "address": {
   9
                  "address_line_1": "1 Market Street",
   10
                  "locality": "San Francisco",
   11
                  "country": "US",
   12
                  "postal_code": "94105",
   13
                  "administrative_district_level_1": "CA"
   14
             },
   15
             "name": "Cash App Pay on Market Street",
   16
             "brand_id": "BRAND_bifwxjq70mfk06l9nr6q4q1f9",
   17
             "country": "US",
   18
            "currency": "USD",
   19
             "category": "5500",
   20
             "reference_id": "external-id"
   21
        },
   22
       "idempotency_key": "b12fa940-d07a-48c6-a08a-89511547661f"
   23
    }'

Step 2: Link a Customer to the Merchant, Brand, or Client

To link a Customer to the Merchant, Brand, or Client, do the following:

1. Create a customer request with one Channel and at least one Action.

   Available Actions	Available Channels
   One Time Payment On File Payment Link Account	IN_APP ONLINE IN PERSON

   See the list of supported actions and channels here. You can have many actions but only one channel.

2. Save the Request ID and the URL from the auth_flow_triggers object in the response.

   When you call create customer request, a customer request is returned to you with auth_flow_triggers populated. This gives you access to URLs including the QR Code URL, Mobile URL, and Desktop URL.

3. Listen for updates to the customer request.

4. When the request enters the approved state, stop polling.

5. Save the Grant IDs listed in the grants array to create a payment later.

   To test the customer request, you can use the Sandbox App or Sandbox Web to scan and approve the request. See more at Sandbox App and Developer Sandbox.

Listen for updates to the customer request

You can listen for updates to the customer request in two ways:

• Polling (recommended): Call retrieve customer request repeatedly (ideally once per second or more frequently).
• Webhooks: Subscribe to the customer_request.state.updated event.

QR codes rotate every 30 seconds and expire every 60 seconds, so you must get the latest QR code. This will change based on how you listen for customer request updates:

• If you are using polling, set the image tag’s URL to the latest QR code that is returned after each polling response. Since you poll more frequently than QR codes rotate, you don’t need to keep track of the refreshes_at value.
• If using webhook, there is no webhook event for QR code rotation. Instead, you should fetch the latest customer request once the current timestamp is after the refreshes_at value. The auth flow triggers will contain the newest, valid QR code.

Example - Create Customer Request

1
curl --location 'https://sandbox.api.cash.app/customer-request/v1/requests' \
2
--header 'Authorization: Client {{client ID}' \
3
--header 'Content-Type: application/json' \
4
--header 'Accept: application/json' \
5
--data '{
6
    "request": {
7
         "actions": [
8
              {
9
                   "amount": 1234,
10
                   "currency": "USD",
11
                   "scope_id": "{{client_id || brand_id || merchant_id}}",
12
                   "type": "ONE_TIME_PAYMENT"
13
14
15
              }
16
         ],
17
         "reference_id": "external-id",
18
         "channel": "ONLINE"
19
    },
20
    "idempotency_key": "cd8b0b0a-0ffb-478e-ae8f-e31aef666a1a"
21
}'

Example - Retrieve Customer Request

1
curl --location --globoff 'https://sandbox.api.cash.app/customer-request/v1/requests/{{customer_request_id}}' \
2
--header 'Authorization: Client {{client_id}}' \
3
--header 'Content-Type: application/json' \
4
--header 'Accept: application/json'

Step 3: Create a Payment

You can now create a payment using the Grant ID and Merchant ID from the previous steps using the Create a payment request endpoint. You can use void, capture, or refund actions depending on the state of the payment.

Example - Create Payment

1
curl --location 'https://sandbox.api.cash.app/network/v1/payments' \
2
--header 'Authorization: {{api_creds}}' \
3
--header 'Content-Type: application/json' \
4
--header 'Accept: application/json' \
5
--header 'X-Region: PDX' \
6
--data '{
7
    "payment": {
8
         "capture": true,
9
         "amount": 1234,
10
         "currency": "USD",
11
         "merchant_id": "{{merchant_id}}",
12
         "grant_id": "{{grant_id}}",
13
         "reference_id": "external-id"
14
    },
15
    "idempotency_key": "2a77b3a5-9104-4587-9517-53ac5d968f25"
16
}'

Notes

Pay Kit SDK

Pay Kit is the name of the Cash App Pay SDK. This SDK specifically handles linking a Customer to a Merchant and uses the Customer Request API underneath. Instead of using the SDK, you can call the APIs directly as described in the steps to integrate with the Cash App Pay API above. To know more about our SDK, see Pay Kit.

Signatures

Cash App Pay Network API and Management API require that all requests be signed. However, when using Sandbox, you can skip this by setting x-signature to the value sandbox:skip-signature-check. Use these Magic Values to control the behavior in Sandbox and to produce preset outcomes.