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:
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.
Charge the payment token - The backend component of your application makes a
CreatePayment
request to charge the payment token. Thesource_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 thesource_id
field.Create payment
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
isWALLET
, which identifies Cash App as the digital wallet payment type.status
isCOMPLETED
. If you setautocomplete
tofalse
in the request, the initial status isAUTHORIZED
. You must then explicitly callCompletePayment
.order_id
identifies theOrder
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, theCreatePayment
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.