Cash App Payments

Applies to: Payments API | Web Payments SDK

Learn how to take Cash App payments using the Payments API.

Applications take Cash App payments using a combination of the Web Payments SDK and the Payments API. You 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.

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 cannot take Cash App payments.

Cash App account information isn't 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

   cURL

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

   {
      "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 don't provide an order, Square creates one.

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

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 value	Error mapping	Expected behavior
  wnon:cash-app-ok		The request is successful.
  wnon:cash-app-declined	GENERIC_DECLINE	The 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 don't 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.