Getting Started

Cash App Pay is now supported as a tender type for Cash App Afterpay customers using the latest afterpay-button.js file.

Note

Cash App Pay is currently only available in the United States. If you are an Australian, Canadian, or United Kingdom merchant, ignore this Cash App Pay section of the guide.

Differences Between Cash App Pay and Cash App Afterpay

It is important to understand the distinction between Cash App Pay and Cash App Afterpay.

Key Differences:

  • Cash App Pay allows customers to pay in a single transaction

  • Cash App Afterpay enables customers split payments into installments

Cash App Pay

A digital payment feature that allows customers to make secure, contactless payments in stores or online from their Cash App balance or linked bank accounts.

Cash App Afterpay

A buy now, pay later service available to US merchants only, allowing customers to split payments into four interest-free installments every six weeks.

Implement Cash App Pay

To enable Cash App Pay, do the following:

  1. Ensure that you are using the latestafterpay-button.js.

    Production | Sandbox

    1<script src="https://static-us.afterpay.com/javascript/button/afterpay-button.js" type="text/javascript"></script>
  2. Add a Cash App Pay Button Element.

    Identical to the Afterpay Button but with an additional isCashAppPay parameter:

    1<afterpay-button isCashAppPay merchantPublicKey="abaa2250913d4db38..."></afterpay-button>
  3. Bind the same order attributes for both Cash App Afterpay and Cash App Pay

    a. Managed UI:**
    Bind the attributes then call afterpayButton.initializeForCashAppPay.

    or

    b. Advanced Rendering Controls:**
    bind the attributes on the click event or within afterpayButton.renderCashAppPayButton.

1const afterpayButtons = document.querySelectorAll('afterpay-button');
2afterpayButtons.forEach(afterpayButton => {
3 /* a.) Managed UI */
4 if (afterpayButton.hasAttribute("isCashAppPay")) {
5 bindAttributesToButton(afterpayButton);
6 afterpayButton.initializeForCashAppPay({
7 // button style configurations
8 button: {
9 size: 'small', // "medium" | "small"
10 width: 'full', // "full" | "static"
11 theme: 'dark', // "dark" | "light"
12 shape: 'round' // "round" | "semiround"
13 },
14 // mobile redirect
15 redirectConfirmUrl: 'https://appsp-sandbox.afterpay-test.repl.co/button',
16 // error callback handler
17 onError: function(event) {
18 console.log(`onError: ${JSON.stringify(event.data, null, 4)}`);
19 },
20 // event.data includes the same virtual card object + the customer's cashtag
21 onComplete: function(event) {
22 const { status, virtualCard, token, cashtag } = event.data;
23 },
24 eventListeners: {
25 CUSTOMER_INTERACTION: ({ isMobile }) => {
26 if (isMobile) {
27 console.log(`Customer is on mobile`);
28 } else {
29 console.log(`Customer is not on mobile`);
30 }
31 },
32 CUSTOMER_REQUEST_DECLINED: () => {
33 console.log(`CUSTOMER_REQUEST_DECLINED`);
34 },
35 CUSTOMER_REQUEST_APPROVED: () => {
36 console.log(`CUSTOMER_REQUEST_APPROVED`);
37 },
38 CUSTOMER_REQUEST_FAILED: () => {
39 console.log(`CUSTOMER_REQUEST_FAILED`);
40 },
41 CUSTOMER_DISMISSED: () => {
42 console.log(`CUSTOMER_REQUEST_FAILED`);
43 }
44 }
45 });
46 }
47 /* b.) Advanced Rendering Controls */
48 // bind the attributes on click for both Afterpay Button and Cash App Pay Button
49 afterpayButton.addEventListener('click', bindAttributesToButton(afterpayButton), true);
50 afterpayButton.hasAttribute("isCashAppPay") && renderCashAppPayButton(afterpayButton);
51})

Process the Credit Card using onComplete

Process the credit card using the onComplete callback, which returns the virtual card object and the customer’s cashtag.

Handling Customer Request Changes

Customer Requests may fail due to premature exits or risk-based declines. Use eventListeners to manage state changes on your frontend.

Note

If a request fails or is declined, dispay an error message such as: Could not link Cash App Pay. Please try again or choose a different payment method.

1afterpayButton.initializeForCashAppPay({
2 // All other configurations
3 eventListeners: {
4 CUSTOMER_INTERACTION: (CustomerInteractionData) => {
5 const { isMobile } = CustomerInteractionData;
6 console.log("CUSTOMER_INTERACTION is on mobile: ", isMobile);
7 },
8 CUSTOMER_REQUEST_DECLINED: () => {
9 console.log(`CUSTOMER_REQUEST_DECLINED`);
10 },
11 CUSTOMER_REQUEST_APPROVED: (CustomerRequestData) => {
12 console.log(`CUSTOMER_REQUEST_APPROVED`);
13 console.log("Customer Request Approved Data: ", CustomerRequestData);
14 },
15 CUSTOMER_REQUEST_FAILED: () => {
16 console.log(`CUSTOMER_REQUEST_FAILED`);
17 },
18 CUSTOMER_DISMISSED: () => {
19 console.log(`CUSTOMER_REQUEST_FAILED`);
20 }
21 }
22});

Event Listener Parameters

NameTypeDescription
type"CUSTOMER_INTERACTION" | "CUSTOMER_DISMISSED" | "CUSTOMER_REQUEST_APPROVED" | CUSTOMER_REQUEST_DECLINED | CUSTOMER_REQUEST_FAILEDevent type
Customer Interaction Data
NameTypeDescription
isMobilebooleantrue if the customer is on a mobile device.
CustomerRequestData
NameTypeDescription
customerProfileCustomerCustomer details.
grantsPartial<Record<keyof Actions, GrantDetail>>Payment grant details.
referenceIdstringA reference to the checkout identifier.
Customer

The Cash App customer who approved the request.

NameTypeDescription
cashtagstringPublic Cash App identifier.
idstringUnique identifier for this customer.
Grants
NameTypeDescription
expiresAtDateGrant expiration date.
grantIdstringGrant ID for payment.

Payment reversals with Cash App

Cash App sales support the standard Cash App Afterpay payment reversal process.

Settlement with Cash App

Cash App Afterpay handles all payment resolutions, with settlement information available as usual.