Cash App Pay payments
Add support for Cash App Pay to your integration.
We recommend you use the Mobile Payment Element, an embeddable payment form, to add Cash App Pay and other payment methods to your integration with the least amount of effort.
This guide covers how to accept Cash App Pay from your native mobile application using your own custom payment form.
If you’re accepting Cash App Pay from your native mobile application, your customers are redirected to the Cash App mobile application for authentication. The purchase is completed in the Cash App mobile application, and the customer is redirected back to your native mobile application.
Set up StripeServer-sideClient-side
First, you need a Stripe account. Register now.
Server-side
This integration requires endpoints on your server that talk to the Stripe API. Use the official libraries for access to the Stripe API from your server:
Client-side
The Stripe iOS SDK is open source, fully documented, and compatible with apps supporting iOS 13 or above.
Note
For details on the latest SDK release and past versions, see the Releases page on GitHub. To receive notifications when a new release is published, watch releases for the repository.
Configure the SDK with your Stripe publishable key on app start. This enables your app to make requests to the Stripe API.
Create a PaymentIntentServer-sideClient-side
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 and confirm a PaymentIntent
on your server:
- Specify the amount to collect and the currency.
- Add
cashapp
to the list of payment method types for yourPaymentIntent
. Make sure Cash App Pay is enabled in the Dashboard. - Set
payment_
tomethod_ data[type] cashapp
to create a PaymentMethod and immediately use it with this PaymentIntent.
The returned PaymentIntent includes a client secret, that you’ll use to confirm the PaymentIntent. Send the client secret back to the client so you can use it in the next step.
Client-side
On the client, request a PaymentIntent from your server and store its client secret.
Submit the payment to StripeClient-side
When a customer taps to pay with Cash App Pay, confirm the PaymentIntent
to complete the payment. Configure an STPPaymentIntentParams
object with the PaymentIntent
client secret.
The client secret is different from your API keys that authenticate Stripe API requests. Handle it carefully, as it can complete the charge. Don’t log it, embed it in URLs, or expose it to anyone but the customer.
Set up a return URL
The iOS SDK presents a webview in your app to complete the Cash App Pay payment. When authentication is finished, the webview can automatically dismiss itself instead of having your customer close it. To enable this behavior, configure a custom URL scheme or universal link and set up your app delegate to forward the URL to the SDK.
Pass the URL as the return_
when you confirm the PaymentIntent. After webview-based authentication finishes, Stripe redirects the user to the return_
.
Confirm Cash App Pay payment
Complete the payment by calling STPPaymentHandler confirmPayment
. This presents a webview where the customer can complete the payment with Cash App Pay. Upon completion, the completion block is called with the result of the payment.
OptionalSeparate authorisation and capture
You can separate authorisation and capture to create a charge now, but capture funds later. Stripe cancels the PaymentIntent and sends a payment_intent.canceled event if the payment isn’t captured during the 7-day window.
If you know that you can’t capture the payment, we recommend cancelling the PaymentIntent instead of waiting for the 7-day window to elapse.
Tell Stripe to authorize only 
To indicate that you want separate authorisation and capture, set capture_method to manual
when creating the PaymentIntent. This parameter instructs Stripe to only authorise the amount on the customer’s Cash App Pay account.
Capture the funds 
After the authorisation succeeds, the PaymentIntent status transitions to requires_
. To capture the authorised funds, make a PaymentIntent capture request.
The total authorized amount is captured by default. You can also specify amount_
which can be less or equal to the total.
Optional Cancel the authorisation
If you need to cancel an authorisation, you can cancel the PaymentIntent.
OptionalHandle post-payment events
Stripe sends a payment_intent.succeeded event when the payment completes. Use the Dashboard, a custom webhook, or a partner solution to receive these events and run actions, like sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.
Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response. Setting up your integration to listen for asynchronous events also helps you accept more payment methods in the future. Learn about the differences between all supported payment methods.
Handle events manually in the Dashboard
Use the Dashboard to View your test payments in the Dashboard, send email receipts, handle payouts or retry failed payments.
Build a custom webhook
Build a custom webhook handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.
Integrate a prebuilt app
Handle common business events, such as automation or marketing and sales, by integrating a partner application.
Test your integration
Test your Cash App Pay integration with your test API keys by viewing the redirect page. You can test the successful payment case by authenticating the payment on the redirect page. The PaymentIntent transitions from requires_
to succeeded
.
To test the case where the user fails to authenticate, use your test API keys and view the redirect page. On the redirect page, click Fail test payment. The PaymentIntent transitions from requires_
to requires_
.
For test manual capture PaymentIntents, the uncaptured PaymentIntent auto-expires 7 days after successful authorisation.
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 AI 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_
.
Other than a payment being declined, for a Cash App Pay PaymentIntent with a status of requires_
, 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_
.
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_ | Enter the appropriate currency. Cash App Pay only supports usd . |
missing_ | Check the error message for more information about the required parameter. |
payment_ | 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_ | Provide a return_ when confirming a PaymentIntent with Cash App Pay. |