Learn how to use the Square Payments API (CreatePayment endpoint) to charge Cash App.
Payments API

Cash App Payments

Applications can take Cash App payments using the Web Payments SDK client-side library and the Payments API. After charging the specified Cash App account, Square deposits the funds in the Square Balance of the seller. This topic explains how to use the Payments API (CreatePayment endpoint) to accept Cash App payments.

You do not specify Cash App account information directly in a CreatePayment request. Instead, you specify a payment token representing a Cash App account. You get this token from the Square Web Payments SDK. Therefore, taking Cash App payment is a two-step process:

  1. Generate a payment token. Web applications integrate the Web Payments SDK client-side library to take Cash App information from buyers. After the account is verified, the SDK generates a payment token.

  2. Charge the payment token. The application makes a server-side CreatePayment call to charge the payment token. The source_id in the request specifies the payment token.

    The following is an example CreatePayment request. It directs Square to charge $100 to the Cash App account identified by the payment token in the source_id.

    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: 2022-09-21' \
      -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}"
      }'

    Square processes the Cash App payment and returns a Payment object in the response as shown:

    • 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/layD0NVOeImmN9PzORnd3fqokeTZY",
           "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"
       }
    }
    

    Some of the highlights in the response are:

    • source_type is WALLET (identifying Cash App as the digital wallet).

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

    • total_money is the sum of amount_money and tip_money. Because the example does not specify a tip when taking the payment, total_money is the same as amount_money.

    • order_id is the order that the Payments API created. For compatibility with other products (for example, the Point of Sale application), all payments taken for a Square seller need an order. If you do not supply an order, the Payments API creates and maintains one automatically.

For an example application, see Web Payments Quickstart.

The following applies 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.

  • Currently, only the Square Web Payments SDK supports Cash App payments.

  • In the current implementation, you cannot store a buyer's Cash App account on file.

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

  • Use a Square-provided Cash App payment token. Square provides a set of fake Cash App payment tokens for Sandbox testing. Using these payment tokens, you can test CreatePayment calls.

    The Sandbox payment tokens are fake (they do not represent a real bank), but the CreatePayment endpoint returns a response as if the payment is processed. For a list of Cash App payment tokens for Sandbox testing, see Sandbox Test Values.

  • Run a sample application with the Web Payments SDK integrated to generate a payment token. This provides you with an end-to-end payment experience of taking an Cash App payment. For step-by-step instructions, see Take Cash App Payments.

    In Sandbox testing, the payment token that the Web Payments SDK generates always results in a successful CreatePayment call.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.