Cash App Pay
Cash App Pay is now supported as a tender type for merchants using Afterpay. On this page are the following sections:
Afterpay Express Checkout does not support Cash App payments.
Using Cash App with Afterpay is currently only supported in the United States.
Integrating Cash App payments using the existing Afterpay API
Accepting Cash App Pay payments uses the standard API for the Afterpay checkout process, with your existing Afterpay credentials. The Afterpay backend handles the transaction with Cash App Pay. The implementation process is as follows:
- Call the Create Checkout API with the addition of the following parameter
isCashAppPay: trueto create an order token. - Use the token in combination with the Standard Checkout flow, but call
AfterPay.initializeForCashAppPayinstead ofAfterpay.like in the code sample below:
function initAfterPay () {
var cashAppPayOptions = {
button: {
size: 'small', // "medium" | "small"
width: 'full', // "full" | "static"
theme: 'dark', // "dark" | "light"
shape: 'round' // "round" | "semiround"
},
redirectUrl: window.location.href, // where mobile customers should be redirected to
onComplete: function(event) {
const { status, cashtag } = event.data;
},
/* Optional event listeners for merchants to track customer behavior and listen for transaction events in the lifecycle */
eventListeners: {
"CUSTOMER_INTERACTION": ({ isMobile }) => {
console.log(`CUSTOMER_INTERACTION`)
if (isMobile) {
// captureMobileMetrics()
} else {
// captureDesktopMetrics()
};
},
"CUSTOMER_REQUEST_DECLINED": () => {
console.log(`CUSTOMER_REQUEST_DECLINED`)
},
"CUSTOMER_REQUEST_APPROVED": () => {
console.log(`CUSTOMER_REQUEST_APPROVED`)
},
"CUSTOMER_REQUEST_FAILED": () => {
console.log(`CUSTOMER_REQUEST_FAILED`)
}
}
}
AfterPay.initializeForCashAppPay({countryCode: "US", token: "001.k4r216fo4qjug8p7ngmqj595v99g3kpd6jh69qf86bgqe97", cashAppPayOptions});
}
- Add a div with
id="cash-app-pay"where you want the Cash App Pay button to be rendered. - On clicking the button the customer is shown a QR code (on desktop)
- If the customer confirms the order, an orderToken, the customer's cashtag, and a SUCCESS status is returned. If the customer cancels the order, the orderToken and CANCELLED status are returned. We recommend that you display the cashtag to the customer on the review or confirmation page. This is an example event object:
event: {
"data": {
"status": "SUCCESS",
"cashtag": "$CASHTAG_C_TOKEN",
"orderToken": "TOKEN",
}
}
- Depending on the Payment Flows you use for Afterpay, you follow the same process to complete an order. Either call Auth or 2a. Direct Capture. You receive an APPROVED or DECLINED status from Afterpay once the Auth or Direct Capture API has been completed.
Mobile Redirection
On Mobile, instead of a QR code, the customer is redirected to the Cash App. When the customer approves, they are returned to the URL specified in the redirectConfirmUrl in the Create Checkout call. This can be the same page where the Cash App Pay button is rendered e.g. merchant.com/checkout, or a new page e.g. merchant.com/review
Query Params can be added to the
redirectConfirmURLIf you want to determine if the page is loading as a result of redirect from the Cash App, you can add a query param to your redirectConfirmURL. e.g.
merchant.com/checkout?cashapppay=true
The
redirectCancelURLis not used by Cash App Pay.On mobile, the customer is always redirected to the
redirectConfirmUrlfor approved and declined flows.
The page the redirectConfirmUrl points to should initialize afterpay.js and define the below onComplete callback on page load:
function onPageLoad () {
var cashAppPayListenerOptions = {
onComplete: function(event) {
const { status, cashtag, orderToken} = event.data;
},
/* Optional event listeners for merchants to track customer behavior and listen for transaction events in the lifecycle */
eventListeners: {
"CUSTOMER_INTERACTION": ({ isMobile }) => {
console.log(`CUSTOMER_INTERACTION`)
if (isMobile) {
// captureMobileMetrics()
} else {
// captureDesktopMetrics()
};
},
"CUSTOMER_REQUEST_DECLINED": () => {
console.log(`CUSTOMER_REQUEST_DECLINED`)
},
"CUSTOMER_REQUEST_APPROVED": () => {
console.log(`CUSTOMER_REQUEST_APPROVED`)
},
"CUSTOMER_REQUEST_FAILED": () => {
console.log(`CUSTOMER_REQUEST_FAILED`)
}
}
}
AfterPay.initializeCashAppPayListeners({countryCode: "US", cashAppPayListenerOptions});
}
Placing another order in a Single Page App
After a successful checkout, the customer may visit another page. Then the customer may return to the checkout page to order without refreshing the page. Or in another scenario, you may want to provide an upsell immediately after the customer completes the checkout.
When you need to take a new order with Cash App Pay, you can call AfterPay.restartCashAppPay:
AfterPay.restartCashAppPay()
When restarted, AfterPay.js "forgets" all previous authorizations and previously charged amounts. It also removes all Cash App Pay UI (for example, the Cash App Pay button, QR code modal, or approved Cashtag).
After restarting you can start another order as usual:
AfterPay.initializeCashAppPayListeners(...)
AfterPay.initializeForCashAppPay(...);
Unknown macro: {countryCode}
);
We recommend that in a single page app, you should call AfterPay.restartCashAppPay whenever the customer leaves the checkout page. When restarting at the exit of each page, if a customer comes back to the checkout page, your initialization flow works as normal. The customer never sees the QR code for a previous customer request.
Payment reversals with Cash App
Cash App sales support the standard Afterpay payment refund and void processes.
Settlement with Cash App
All payment resolution is handled by Afterpay. Your settlement information differentiates between Afterpay and Cash App sales.
Customer On-File Payments
Cash App Pay makes it easy to checkout and make future purchases through an on-file payment grant.
Cash App Pay calls this on-file payment grant Cashtag on file. The on-file payment grant is created and associated with the merchant’s customer account. Then the merchant uses the on-file payment grant to charge the customer when they shop at the merchant’s online store.
On-File payment grants make future purchases easier and quicker for the customer. This is because the customer does not have to add their payment information and approve the payment every time they make a transaction. There is no need for the customer to go through an approval process, as merchants know the customer, and the customer is registered with Cash App.
Follow the sections and steps below to enable this feature:
Setup Cash App as a Payment Method
When the customer approves the purchase, you, the merchant, get a Cash App on-file payment grant. You use this grant to associate and store with the customer’s account for future purchases. Use the example code below:
function initializeForCashAppOnFileGrant() {
var cashAppPayOnFileOptions = {
button: false, // set to false if using custom button
onComplete: function(event)
{ // returns grantId, expiresAt, cashTag, id }
,
redirectUrl: "https://www.example.com", // where mobile customers should be redirected to
cashAppBrandId: "BRAND_xxxxxxxxxx"
}
AfterPay.initializeForCashAppOnFileGrant({
countryCode: "US",
cashAppPayOnFileOptions
});
}
Purchase Flow
For a signed-in customer, you, the merchant, can use a Cash App grant to complete a Cash App pay purchase. We assume that you have called CreateCheckout with the isCashAppPay field set to True.
An additional argument is added to the payload for authorization/direct capture requests for Afterpay API version 1, and version 2.
For example, this $25 transaction:
{
"requestId": "921F13B5-6210-45A0-AEA8-07296CC9E155",
"token": "002.12sEvVdL3xWaLYNAA8CLQLBA0qQraIcH7VJUg4h8NHODdAP61D",
"merchantReference": "merchant-reference",
"amount":
{ "amount": "25.00", "currency": "USD" }
,
"grantId": "cash-app-grant-id"
}
Note
In the example above, notice the
grantIdfield on the last line.
Setup Cash App as Payment Methods During the Purchase Flow
From your point of view, this is a combination of the two previous use cases above.
To combine the flows, include the requestOnFileGrant: true within cashAppPayOptions for Afterpay.initializeForCashAppPay().
Here is the code snippet for combined flow:
function initAfterPay () {
var cashAppPayOptions = {
requestOnFileGrant: true
button: {
size: 'small', // "medium" | "small"
width: 'full', // "full" | "static"
theme: 'dark', // "dark" | "light"
shape: 'round' // "round" | "semiround"
},
redirectUrl: window.location.href, // where mobile customers should be redirected to
onComplete: function(event) {
const { status, cashtag } = event.data;
},
/* Optional event listeners for merchants to track customer behavior and listen for transaction events in the lifecycle */
eventListeners: {
"CUSTOMER_INTERACTION": ({ isMobile }) => {
console.log(`CUSTOMER_INTERACTION`)
if (isMobile) {
// captureMobileMetrics()
} else {
// captureDesktopMetrics()
};
},
"CUSTOMER_REQUEST_DECLINED": () => {
console.log(`CUSTOMER_REQUEST_DECLINED`)
},
"CUSTOMER_REQUEST_APPROVED": () => {
console.log(`CUSTOMER_REQUEST_APPROVED`)
},
"CUSTOMER_REQUEST_FAILED": () => {
console.log(`CUSTOMER_REQUEST_FAILED`)
}
}
}
AfterPay.initializeForCashAppPay({countryCode: "US", token: "001.k4r216fo4qjug8p7ngmqj595v99g3kpd6jh69qf86bgqe97", cashAppPayOptions});
}
Note
This code above is identical to the code in the Integrating Cash App payments using the existing Afterpay API section, except for
requestOnFileGrant: trueinsidecashAppPayOptions.
Updated about 1 month ago