# Process payments outside the App Store

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](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app.md) to process payments for physical goods and services, because it provides an integrated checkout experience directly within your app.

---

## Regulatory mandates and geographic availability

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

### European Union

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:

- [Update on apps distributed in the European Union](https://developer.apple.com/support/dma-and-apps-in-the-eu/)
- [Alternative payment options on the App Store in the European Union](https://developer.apple.com/support/alternative-payment-options-on-the-app-store-in-the-eu/)

### United States

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](https://developer.apple.com/support/storekit-external-entitlement-us/).

### Other regions

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](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/get-started-with-flow.md) in your website. Then, call the appropriate [Universal Links](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app) that your app manages.

---

## Before you start

1. Review the [Accept a payment on a hosted page](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-a-hosted-page.md) documentation to understand the fundamental integration principles.
2. Ensure you stay updated with Apple's latest App Store policies and developer guidelines.

---

## How it works

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

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

## Generate a Hosted Payments Page session

1. Call the [Create a Hosted Payments Page session](https://api-reference.checkout.com/tag/Hosted-Payments-Page/#operation/createAHostedPaymentsSession) 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.

2. Send the payment page link from your back-end to your app.
3. 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 Safari, and not in a WebView.

## Implement Universal Links

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](https://developer.apple.com/library/archive/documentation/General/Conceptual/AppSearch/UniversalLinks.html) for more information.

### Configure your app

1. Open your app project in Xcode.
2. Go to your app's target settings.
3. Select the _Signing & Capabilities_ tab.
4. Select the `+` button to add a new capability.
5. Search for _Associated Domains_, and add it.
6. 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`.

### Configure your websites

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:

```json
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "YOUR_TEAM_ID.YOUR_BUNDLE_ID",
        "paths": [
          "/hpp/success",
          "/hpp/failure",
          "/hpp/cancel"
          ]
      }
    ]
  }
}
```

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](https://developer.apple.com/documentation/xcode/supporting-associated-domains) for more information.

---

## Extract payment information from the response

1. In your [Create a Hosted Payments Page session](https://api-reference.checkout.com/tag/Hosted-Payments-Page/#operation/createAHostedPaymentsSession) 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`

2. 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.
3. Implement logic within your app to handle the incoming URLs. <br>
In SwiftUI, this is typically done using the `.onOpenURL` modifier attached to a view.
4. 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`:

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

---

## Update your app UI

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.

---

## Verify the payment status

You must always verify the payment's status by listening to the relevant webhook. This applies even if your app receives a redirection to your `success_url` through a Universal Link and extracts a `cko-payment-id`.
See [Confirm the payment status](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-a-hosted-page/manage-your-hosted-payments-page.md#Confirm_the_payment_status) for more information.

> **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 confirming the payment status from the relevant webhooks.