Learn how to add Cash App Pay as a payment method to an application.
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
Web Payments SDK

Take a Payment with Cash App Pay

Cash App Pay lets customers seamlessly pay with their Cash App account, enabling a fast and familiar checkout experience using a mobile payment application. Now you can add Cash App Pay to customers' online checkout flow built on Square Web Payments SDK.

The following video demonstrates how to implement Cash App Pay. For a detailed overview of building with the card payment method, see the following sections in this topic.

Note

Cash App Pay is currently supported only in the United States. If you implement Cash App Pay for a seller that is based outside of the US, the Cash App Pay button and payment method doesn't render in your application.

Link to section
Overview

Learn how to add a Cash App Pay payment method to the application you built using the Quickstart project sample in Take a Card Payment with the Web Payments SDK to integrate the Web Payments SDK into your application.

The steps in this topic add code to the application you created from the Quickstart project sample. If you haven't created an application using the Quickstart, you need to do so before completing the steps in this topic.

You can find a full example of the Cash App Pay code on GitHub.

Link to section
Add the Cash App Pay payment method to the page

The Cash App Pay payment method needs information about the buyer and the payment amount before it can open the Cash App payment sheet. Your application creates a PaymentRequest object to provide that information and then gets a new CashAppPay object initialized with it.

The following code creates the payment request and attaches the Cash App payment method to the page:

  1. Add an HTML element to the prerequisite walkthrough form with an id of cash-app-pay. The HTML for the body of index.html should look like the following:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    <form id="payment-form">
   <!-- Add the cash-app-pay button div below -->
   <div id="cash-app-pay"></div>
   <div id="card-container"></div>
   <button id="card-button" type="button">Pay $1.00</button>
</form>
<div id="payment-status-container"></div>

  2. Add the following two functions to your script tag:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  function buildPaymentRequest(payments) {
    const paymentRequest = payments.paymentRequest({
      countryCode: 'US',
      currencyCode: 'USD',
      total: {
        amount: '1.00',
        label: 'Total',
      }
    });
    return paymentRequest;
  }

  async function initializeCashApp(payments) {
    const paymentRequest = buildPaymentRequest(payments)
    const cashAppPay = await payments.cashAppPay(paymentRequest,{
      redirectURL: 'https://my.website/checkout',
      referenceId: 'my-website-00000001',
    });
    await cashAppPay.attach('#cash-app-pay');
    return cashAppPay;
  }

The initializeCashApp function requires a redirectURL value to indicate where to send buyers after completing a payment on a mobile device. The redirectURL value is only for mobile payments and isn't used for desktop QR payments.

You can also include the optional referenceID payment identifier value for internal developer use. For example, you use a 'referenceId' value to associate the payment with an internal resource.

  1. In the DOMContentLoaded event listener, add the following code after you initialize the Cash App payment method:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
      let cashAppPay;
  try {
    cashAppPay = await initializeCashApp(payments);
  } catch (e) {
    console.error('Initializing Cash App Pay failed', e);
  }

Link to section
Test the application

Navigate to http://localhost:3000/ in your browser.

Checkpoint 1: You should now see the Cash App Pay button rendered on your page.

A screenshot of the rendered Cash App Pay payment button on a web page payment client.

Link to section
Get the payment token from the Cash App Pay payment method and attach it to a DOM element

Add the following code after // Checkpoint 2 in the DOMContentLoaded event listener function, to listen for the ontokenization:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
cashAppPay.addEventListener('ontokenization', function (event) {
  const { tokenResult, error } = event.detail;
  if (error) {
    // developer handles error
  }
  else if (tokenResult.status === 'OK') {
    // developer passes token to backend for use with CreatePayment
  }
});

This event fires when a buyer authorizes a payment in Cash App, is taken back to the merchant website redirectUri (if mobile), and a payment token (nonce) is ready.

Note how Cash App Pay has its own event listeners on the PaymentRequest object and how these event listeners have their own specific callbacks. For more information, see addEventListener.

Link to section
Test the application

Test the Cash App payment flow from the browser in the sandbox environment.

The following animation shows the Cash App Pay payment flow: A screenshot shows the dialog box of the approved Cash App linked account.

Important

When you test the Cash App and Web Payments SDK integration in a production environment, you can use both the Cash App camera and the smartphone camera to scan the QR code. When you test the payment flow in a sandbox environment, the sandbox environment only supports using the smartphone camera to scan the QR code.

  1. Navigate to http://localhost:3000/ in your browser.

  2. Click the Cash App Pay button.

You should see the Cash App Pay dialog box appear with the QR code.

  1. Using your smartphone's camera, scan the QR code in the dialog box.

On your smartphone's web browser at sandbox.api.cash.app, the application displays a dialog requesting permission to approve or decline the request to link the account.

A screenshot of the application dialog box requesting permission to approve or decline the request to link the account.

  1. Tap Approve to link the account.

Checkpoint 2. You should now receive a confirmation that the account has been linked.

Dialog box of approved Cash App linked account on sandbox

Link to section
Process a Cash App Pay payment token on your backend

The payment token that your application generated for a Cash App Pay payment is processed on your backend in the same way a payment token from one of the other payment methods is processed, with some exceptions. To learn about the specific processing requirements, see Cash App Payments.

Link to section
Limitations

The following limitations apply after integrating the Web Payments SDK to add Cash App Pay:

  • Cash App Pay currently doesn't support changing or updating the options specified in a PaymentRequest object. This limitation occurs when the browser displays the Google Pay payment sheet for the buyer.

  • CBD sellers can't take Cash App payments.

Link to section
Build additional controls for payments

The Pay Kit JavaScript SDK includes methods to present the Cash App Pay payment method and controls for handling payment requests. The SDK also provides advanced controls for situations where you need to validate customer information or customize the Cash App Pay checkout experience.

For more information, see Cash App's technical reference for Pay Kit use cases.

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