Accept payments for digital goods on iOS with a custom checkout page

First, register for a Stripe account.

Then add the Stripe API library to your backend:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Next, install the Stripe CLI. The CLI provides the required webhook testing, and you can run it to create your products and prices.

# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe

# Connect the CLI to your dashboard
stripe login

For additional install options, see Get started with the Stripe CLI.

Create your products and their prices in the Dashboard or with the Stripe CLI.

This example uses a single product and price to represent a subscription product with a $9.99 USD monthly price.

Navigate to the Add a product page and create a subscription product with a 9.99 USD monthly price.

After you create the price, record the price ID so you can use it in subsequent steps. Price IDs look like this: price_G0FvDp6vZvdwRZ.

Next, click Copy to live mode to clone your product from a testing environment to live mode.

Each time your customer goes to your checkout page, create a Customer object for your customer if one doesn’t already exist.

Your server needs to handle:

• Customer creation (if a matching Stripe Customer doesn’t exist yet).
• Subscription creation in an incomplete state.
• Returning the PaymentIntent client secret to the front end.
• Webhook handling so you can update your customer’s subscription status in your own database.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2');


// This assumes your app has an existing user database, which we'll call `myUserDB`.
const user = myUserDB.getUser("jennyrosen");


if (!user.stripeCustomerID) {
 const customer = await stripe.customers.create({
   name: user.name,
   email: user.email,
 });


 // Set the user's Stripe Customer ID for later retrieval.
 user.stripeCustomerID = customer.id;
}

When creating a subscription to use the Payment Element, you typically pass payment_behavior: 'default_incomplete'. This tells Stripe to create a subscription in incomplete status and generate a Payment Intent for the initial payment.

// This example sets up an endpoint using the Express framework.
// Watch this video to get started: https://youtu.be/rPR2aJ6XnAc.


const express = require('express');
const app = express();
const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2')


app.post('/create-subscription', async (req, res) => {
 const { priceId, customerId } = req.body;


 // Create the subscription
 // setting payment_behavior to "default_incomplete" ensures we get a Payment Intent
 // that we can confirm on the client using the Payment Element
 const subscription = await stripe.subscriptions.create({
   customer: customerId,
   items: [{ price: priceId }],
   payment_behavior: 'default_incomplete',
   expand: ['latest_invoice.payment_intent'],
 });


 // Make sure you associate the subscription ID with the user in your database!
 myUserDB.addUserSubscription("jennyrosen", subscription.id);


 // Get the Payment Intent client secret
 const paymentIntent = subscription.latest_invoice.payment_intent;
 const clientSecret = paymentIntent.client_secret;


 return res.json({
   subscriptionId: subscription.id,
   clientSecret: clientSecret,
 });
});


app.post('/login', async (req, res) => {
 // This assumes your app has an existing user database, which we'll call `myUserDB`.
 const token = myUserDB.login(req.body.login_details)
 res.json({token: token})
});


app.listen(4242, () => console.log(`Listening on port ${4242}!`));

Universal links allow your checkout page to deeply link into your app. To configure a universal link:

• Add an apple-app-site-association file to your domain.
• Add an Associated Domains entitlement to your app.
• Add a fallback page for your checkout redirect URLs.

Define the associated domains

Add a file to your domain at .well-known/apple-app-site-association to define the URLs that your app handles. Prepend your App ID with your Team ID, which you can find on the Membership page of the Apple Developer Portal.

{
 "applinks": {


     "apps": [],
     "details": [
          {
            "appIDs": [ "A28BC3DEF9.com.example.MyApp1",
                        "A28BC3DEF9.com.example.MyApp1-Debug" ],
            "components": [
              {
                 "/": "/checkout_redirect*",
                 "comment": "Matches any URL whose path starts with /checkout_redirect"
              }
            ]
          }
      ]
  }
}

curl -I https://example.com/.well-known/apple-app-site-association

See Apple’s page on supporting associated domains for more details.

Add an Associated Domains entitlement to your app

1. Open the Signing & Capabilities pane of your app’s target.
2. Click + Capability, then select Associated Domains.
3. Add an entry for applinks:yourdomain.com to the Associated Domains list.

For more information on universal links, see Apple’s universal links documentation.

Although iOS intercepts links to the URLs defined in your apple-app-site-association file, you might encounter situations where the redirect fails to open your app.

Create a fallback page at your success and cancel URLs. For example, you can have a /checkout_redirect/success page and a /checkout_redirect/cancel page.

Add a checkout button to your app. This button opens your custom checkout page in Safari.

import Foundation
import SwiftUI
import StoreKit


struct BuySubscriptionsView: View {
   @EnvironmentObject var myBackend: MyBackend
   @State var paymentComplete = false


   var body: some View {
       // Check if payments are blocked by Parental Controls on this device.
       if !SKPaymentQueue.canMakePayments() {
           Text("Payments are disabled on this device.")
       } else {
           if paymentComplete {
               Text("Payment complete!")
           } else {
               Button {
                   UIApplication.shared.open("https://example.com/checkout", options: [:], completionHandler: nil)
               } label: {
                   Text("Subscribe")
               }.onOpenURL { url in
                   // Handle the universal link from Checkout.
                   if url.absoluteString.contains("success") {
                       // The payment was completed. Show a success
                       // page and fetch the latest customer entitlements
                       // from your server.
                       paymentComplete = true
                   }
               }
           }
       }
   }
}

With Elements, make sure you redirect users back to your app (using the registered universal link) on a successful payment confirmation.

stripe.confirmPayment({
  elements,
  confirmParams: {
    // Return URL where the customer should be redirected after the PaymentIntent is confirmed.
    return_url: 'https://example.com/checkout_redirect/success',
  },
})
.then(function(result) {
  if (result.error) {
    // Inform the customer that there was an error.
  }
});

When the user completes the initial payment or when subsequent recurring payments occur, Stripe sends events such as:

• invoice.payment_succeeded
• customer.subscription.updated
• invoice.payment_failed

Listen for these events in your webhook endpoint. For example:

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
 const sig = req.headers['stripe-signature'];
 let event;


 try {
   event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET);
 } catch (err) {
   console.error('Webhook signature verification failed.', err.message);
   return res.sendStatus(400);
 }


 switch (event.type) {
   case 'invoice.payment_succeeded': {
     const invoice = event.data.object;
     // Mark subscription as active in your database
     // e.g., invoice.subscription -> "sub_abc123"
     console.log('Payment succeeded');
     break;
   }
   case 'invoice.payment_failed': {
     const invoice = event.data.object;
     console.log('Payment failed - notify the user to update their payment methods');
     break;
   }
   case 'customer.subscription.updated': {
     const subscription = event.data.object;
     // e.g., handle pause, cancellation, or other changes
     console.log(`Subscription updated: ${subscription.id}`);
     break;
   }
   default:
     console.log(`Unhandled event type ${event.type}`);
 }
  res.json({ received: true });
});

To test your integration, you can monitor events in the Dashboard or using the Stripe CLI. When developing in production, set up a webhook endpoint and subscribe to appropriate event types. If you don’t know your STRIPE_WEBHOOK_SECRET key, click the webhook in the Dashboard to view it.

Testing

To test your that your checkout button works, do the following:

1. Click the checkout button, which redirects you to your checkout with Stripe’s Payment Element.
2. Enter the test number 4242424242424242
   , a three-digit CVC, a future expiration date, and any valid postal code.
3. Tap Pay.
4. The invoice.payment_succeeded webhook fires, and Stripe notifies your server about the transaction.
5. You’re redirected back to your app.

If your integration isn’t working, see additional testing resources.