Process payments outside the App Store

Last updated: May 14, 2025

You can integrate the Hosted Payments Page solution with your iOS app to sell digital goods and services, and process payments outside of Apple's In-App Purchases system.

Checkout.com recommends using Flow for mobile to process payments for physical goods and services, because it provides an integrated checkout experience directly within your app.

The way digital goods are sold on mobile platforms is subject to legal and regulatory mandates as follows:

To comply with the Digital Markets Act (DMA), Apple introduced changes for apps distributed in the EU from March 2024. Developers can direct users to external websites to purchase digital goods and services, including using alternative payment processors. Developers must agree to Apple's Alternative Terms Addendum for Apps in the EU.

For more information, see Apple:

Apple allows developers to include a link in their app to their website to inform users of other ways to purchase digital goods.

Specific entitlements and conditions apply, including commission rates on transactions initiated through these external links.

For more information, see Apple – Distributing apps in the U.S. that provide an external purchase link.

Policies regarding external payment links for digital goods can vary by region and are subject to change. Ensure you read the latest App Store review guidelines and developer agreements for your target markets.

In regions where Apple's policies permit, you can embed a Hosted Payments Page in your app to route customers to your website to complete payments for digital goods and services.

Information

Alternatively, you can integrate Flow in your website. Then, call the appropriate Universal Links that your app manages.

Review the Accept a payment on a hosted page documentation to understand the fundamental integration principles.
Ensure you stay updated with Apple's latest App Store policies and developer guidelines.

Follow these steps to integrate the Hosted Payments Page with your iOS app using Universal Links:

Generate a Hosted Payments Page session and open the link in your app.
Implement Universal Links and configure them for your app and website.
Extract the payment information from the response.
Update your app's UI.
Verify the payment status.

Call the Create a Hosted Payments Page session endpoint, using your Checkout.com secret key.

Note

To prevent security vulnerabilities, never embed your secret key directly in your app. Your back-end must call the API and receive the Hosted Payments Page link in the response.

Send the payment page link from your back-end to your app.
Open the link in Safari to redirect the user to the payment page.

Information

In some regions, such as the US, Apple requires the payment page link to open in a new window in the default browser, and not in a WebView.

To ensure a smooth user experience where the customer is redirected back to your app after completing the payment flow, your app must support Universal Links. See Apple – Supporting Universal Links for more information.

Open your app project in Xcode.
Go to your app's target settings.
Select the Signing & Capabilities tab.
Select the + button to add a new capability.
Search for Associated Domains, and add it.
Under the Associated Domains section, add an entry for each domain that you want your app to support, prefixed with applinks:. For example, applinks:yourdomain.com.

You must securely associate your websites with your app by adding an associated domain file.

Create an apple-app-site-association file (without an extension) on your website and list the domains you set in the Associated Domains section for your app.

You must explicitly list the success_url, failure_url, and cancel_url paths in the paths array in your apple-app-site-association file:


1{
2  "applinks": {
3    "apps": [],
4    "details": [
5      {
6        "appID": "YOUR_TEAM_ID.YOUR_BUNDLE_ID",
7        "paths": [
8          "/hpp/success",
9          "/hpp/failure",
10          "/hpp/cancel"
11          ]
12      }
13    ]
14  }
15}

Replace YOUR_TEAM_ID.YOUR_BUNDLE_ID with your Apple Team ID and your app's Bundle Identifier.

The associated domain file:

Is JSON formatted
Must be accessible via HTTPS without any redirects
Must be located either at https://yourdomain.com/apple-app-site-association or https://yourdomain.com/.well-known/apple-app-site-association

See Apple – Supporting associated domains for more information.

In your Create a Hosted Payments Page session request, set the success_url, failure_url, and cancel_url fields. These URLs must point to specific paths on your domain that are configured for Universal Links. For example:
- https://yourdomain.com/hpp/success
- https://yourdomain.com/hpp/failure
- https://yourdomain.com/hpp/cancel
When the customer completes the Hosted Payments Page flow, Checkout.com redirects them to the relevant URL. Because these are Universal Links, iOS intercepts them and routes them to your app.
Implement logic within your app to handle the incoming URLs.
In SwiftUI, this is typically done using the .onOpenURL modifier attached to a view.
Inside the handler, you must:
1. Receive the incoming URL.
2. Verify the scheme and host to ensure it's a legitimate Hosted Payments Page callback from your domain.
3. Parse the path of the URL to determine the outcome of the payment attempt. For example, /hpp/success, /hpp/failure, /hpp/cancel.
4. Extract the query parameters.

Checkout.com often appends useful information to the callback URLs as query parameters. For example, the cko-payment-id query parameter.

You can extract this parameter using URLComponents:


1// ... Inside your .onOpenURL handler or a called function
2let components = URLComponents(url: incomingURL, resolvingAgainstBaseURL: false)
3if let queryItems = components?.queryItems {
4    if let paymentIDItem = queryItems.first(where: { $0.name == "cko-payment-id" }) {
5        let paymentID = paymentIDItem.value // Store and use this payment ID
6    }
7}
8// ...

Update your app UI and take the necessary actions based on the path and any extracted data. For example, display a success message with the payment ID, show an error, or return to the cart.

You must always verify the payment's status by querying your backend. This applies even if your app receives a redirection to your success_url through a Universal Link and extracts a cko-payment-id.

Make a server-to-server call from your back-end to the Checkout.com API to confirm the payment status, using one of the following:

cko-payment-id
Hosted Payments Page session ID

Note

Do not rely only on the front-end redirection as confirmation that the payment was successful. You must manage finalizing the order or granting access to digital content in your back-end after the server-side verification.

Process payments outside the App Store

Regulatory mandates and geographic availability

European Union

United States

Other regions

Information

Before you begin

How it works

Generate a Hosted Payments Page session

Note

Information

Implement Universal Links

Configure your app

Configure your websites

Extract payment information from the response

Update your app UI

Verify the payment status

Note