Cash App Pay payments

Learn how to accept Cash App Pay, a digital wallet popular with US customers.

Web

Mobile

We recommend that you implement the custom payment flow integration. The custom payment flow allows you to add Cash App Pay and other payment methods to your integration with the least amount of effort. Accepting Cash App Pay using a Direct API integration consists of:

Creating a PaymentIntent object to track a payment.
Submitting the payment to Stripe for processing.
Authenticating the payment (through a mobile application redirect or QR code).
Handling post-payment events to redirect the customer after an order succeeds or fails.

Set up Stripe
Server-side

First, you need a Stripe account. Register now.

Use our official libraries for access to the Stripe API from your application:

Create a PaymentIntent
Server-side

A PaymentIntent is an object that represents your intent to collect payment from a customer and tracks the lifecycle of the payment process through each stage.

To create a PaymentIntent on your server:

Specify the amount to collect and the currency.
Add cashapp to the list of payment method types for your PaymentIntent. Make sure Cash App Pay is enabled in the Dashboard.

Retrieve the client secret

The PaymentIntent includes a client secret that the client side uses to securely complete the payment process. You can use different approaches to pass the client secret to the client side.

Retrieve the client secret from an endpoint on your server, using the browser’s fetch function. This approach is best if your client side is a single-page application, particularly one built with a modern frontend framework like React. Create the server endpoint that serves the client secret:

And then fetch the client secret with JavaScript on the client side:

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Submit the payment to Stripe and authenticate transactions client-side

In this step, you’ll complete Cash App Pay payments on the client with Stripe.js. To authenticate a transaction, you must redirect the customer to Cash App.

Include the Stripe.js script on your checkout page by adding it to the head of your HTML file.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/v3/"></script>
</head>

Create an instance of Stripe.js with the following JavaScript on your checkout page:

client.js
// Set your publishable key. Remember to change this to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Use stripe.confirmCashappPayment to confirm the PaymentIntent on the client side.

client.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', function(event) {
  event.preventDefault();

  // Pass the clientSecret obtained from the server in step 2 as the first argument
  stripe.confirmCashappPayment(
    clientSecret,
    {
      payment_method: {
        type: 'cashapp',
      },
      return_url: 'https://www.example.com/checkout/done',
    },
  );
});

Caution

confirmCashappPayment only redirects mobile browsers to your return_url, it doesn’t redirect desktop browsers. You can manually redirect customers using desktop browsers to your return URL after the returned promise resolves.

Customers can authenticate Cash App Pay transactions with mobile or desktop apps. The client the customer is using determines the authentication method after calling confirmCashappPayment.

After calling confirmCashappPayment, the customers are redirected to Cash App to approve or decline the payment. After the customers authorize the payment, they’re redirected to the Payment Intent’s return_url. Stripe adds payment_intent, payment_intent_client_secret, redirect_pm_type, and redirect_status as URL query parameters (along with any existing query parameters in the return_url).

An authentication session expires after 60 minutes, and the PaymentIntent’s status transitions back to require_payment_method. After the status transitions, the customer sees a payment error and must restart the payment process.

OptionalHandle redirect and authentication manually

OptionalSeparate authorization and capture

OptionalHandle post-payment events

Test your integration

To test your integration, choose Cash App Pay as the payment method and tap Pay. In test mode, this redirects you to a test payment page where you can approve or decline the payment.

In live mode, tapping Pay redirects you to the Cash App mobile application—you don’t have the option to approve or decline the payment within Cash App. The payment is automatically approved after the redirect.

Failed payments

Cash App Pay uses multiple data points to decide when to decline a transaction (for example, their machine learning model detected high consumer fraud risk for the transaction, or the consumer has revoked your permission to charge them in Cash App).

In these cases, the PaymentMethod is detached and the PaymentIntent object’s status automatically transitions to requires_payment_method.

Other than a payment being declined, for a Cash App Pay PaymentIntent with a status of requires_action, customers must complete the payment within 10 minutes after they’re redirected to Cash App. If no action is taken after 10 minutes, the PaymentMethod is detached and the PaymentIntent object’s status automatically transitions to requires_payment_method.

When this happens, the Payment Element renders error messages and instructs your customer to retry using a different payment method.

Error codes

The following table details common error codes and recommended actions:

Error Code	Recommended Action
`payment_intent_invalid_currency`	Enter the appropriate currency. Cash App Pay only supports `usd`.
`missing_required_parameter`	Check the error message for more information about the required parameter.
`payment_intent_payment_attempt_failed`	This code can appear in the last_payment_error.code field of a PaymentIntent. Check the error message for a detailed failure reason and suggestion on error handling.
`payment_intent_redirect_confirmation_without_return_url`	Provide a `return_url` when confirming a PaymentIntent with Cash App Pay.