Learn how to use the Square Payments API (CreatePayment endpoint) to charge Cash App.
Docs Home
Dev Essentials
Payments Commerce Customers Staff Merchants
Partnerships
Release notes

Docs

Docs Home
Dev Essentials
Payments
Commerce
Customers
Staff
Merchants
Partnerships
Release notes
Docs
Payments API

Cash App Payments

Applications take Cash App payments using a combination of the Web Payments SDK and the Payments API. This topic explains how to use the Payments API CreatePayment endpoint on your backend to process a Cash App payment. The client side is explained in Take a Payment with Cash App Pay.

Link to section
Process a Cash App payment

Cash App account information is not directly specified in a CreatePayment request. Instead, that information is gathered by the Web Payments SDK, which returns a payment token for use in the CreatePayment request. Taking Cash App payments requires the following steps:

  1. Generate a payment token. Your web application uses the Web Payments SDK to get Cash App information from a buyer. The SDK generates a payment token after validating the buyer's Cash App account.

  2. Charge the payment token. The backend component of your application makes a CreatePayment request to charge the payment token. The source_id field in the request is set to the payment token.

    The following example shows a CreatePayment request. It directs Square to charge $100 USD to the Cash App account identified by the payment token in the source_id field.

    Create Payment
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 10000,
      "currency": "USD"
    },
    "source_id": "{PAYMENT_TOKEN}"
  }'
    Try in API Explorer

    Square processes the payment and returns a Payment object in the response.

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    • 31
    • 32
    • 33
    • 34
    • 35
    • 36
    • 37
    {
   "payment": {
       "id": "layD0NVOeImmN9PzORnd3fqokeTZY",
       "created_at": "2021-04-30T21:21:33.721Z",
       "updated_at": "2021-04-30T21:21:36.960Z",
       "amount_money": {
           "amount": 1000,
           "currency": "USD"
       },
       "status": "COMPLETED",
       "delay_duration": "PT168H",
       "source_type": "WALLET",
       "location_id": "LH3FN1WYPN1B7",
       "order_id": "iOpdUUwE7VEFb3ZimOlqKbJlD7eZY",
       "total_money": {
           "amount": 1000,
           "currency": "USD"
       },
       "approved_money": {
           "amount": 1000,
           "currency": "USD"
       },
       "receipt_number": "layD",
       "receipt_url": "https://squareupsandbox.com/receipt/preview/lyD...kZY",
       "delay_action": "CANCEL",
       "delayed_until": "2021-05-07T21:21:33.721Z",
       "wallet_details": {
           "status": "CAPTURED",
           "brand": "CASH_APP",
           "cash_app_details": {
               "buyer_country_code": "US",
               "buyer_cashtag": "$cashtag"
           }
       },
       "version_token": "8QRBlDHFI94bd1c15UU5lcAHnygDWN8KpK7B6FQDyeD6o"
   }
}

    The following are important response details:

    • source_type is WALLET, which identifies Cash App as the digital wallet payment type.

    • status is COMPLETED. If you set autocomplete to false in the request, the initial status is AUTHORIZED. You must then explicitly call CompletePayment.

    • order_id identifies the Order that Square created. For compatibility with other Square products, all payments taken for a Square seller need an order. If you do not provide an order, Square creates one.

To run a Cash App payment example, see Web Payments Quickstart on GitHub.

Link to section
Test Cash App payments in the Square Sandbox

To test Cash App payments in the Square Sandbox, get a test payment token using one of the following methods:

  • Use a Square-provided Cash App payment token. Square provides Cash App Sandbox payment tokens as source_id values for testing the backend component of your application.

    source_id valueError mappingExpected behavior
    wnon:cash-app-okThe request is successful.
    wnon:cash-app-declinedGENERIC_DECLINEThe request failed.
    When you use these tokens, you can test CreatePayment calls without charging an actual Cash App account or running the client side of your application. The tokens do not represent a live Cash App account. However, the CreatePayment endpoint returns a payment response as if the account is real.

    Note

    Be sure to make the CreatePayment call against your Square Sandbox environment (connect.squareupsandbox.com) when using these tokens.

  • Run the Web Payments SDK sample application to generate a payment token. The sample provides an end-to-end Cash App payment experience. For information about building and running the sample, see Take a Payment with Cash App Pay.

    The payment token that the Web Payments SDK generates in Sandbox mode results in a successful CreatePayment Sandbox environment call.

Link to section
Limitations

The following limitations apply when using the Payments API for Cash App payments:

  • Cash App payments are supported only in the United States. Only buyers in the United States can choose Cash App as a payment option.

  • Only the Web Payments SDK supports Cash App payments.

  • You cannot store a buyer's Cash App account on file.

  • CBD sellers can not take Cash App payments.

On this page
We've made improvements to our docs.
Prefer the old format?