# Hybrid API Integration: Advanced
source: https://developer.mastercard.com/mastercard-benefits-and-experiences-portal/documentation/use-cases/use-cases-9/index.md

## Hybrid API Integration Sequence {#hybrid-api-integration-sequence}

This use case shows how to maintain discovery and product detail in your own interface, prepare checkout through API calls, and then redirect the cardholder to a Priceless-hosted checkout page.
Note: PCI compliance and Single Sign-On (SSO) are required for this flow. To learn about the benefits and implementation of SSO, see [User Tokens](https://developer.mastercard.com/mastercard-benefits-and-experiences-portal/documentation/use-cases/use-cases-3/index.md).

**Context:** Partner manages discovery and product detail in partner UI and uses hosted checkout for payment.

**Goal:** Enable cardholders to select a product in partner UI and open a ready-to-pay hosted checkout page.

**Main actors:** Cardholder, Partner app or website, Partner backend, Priceless APIs, Priceless-hosted checkout page.

**Preconditions:**

* The content strategy is agreed.
* The partner is enabled for Hybrid API Integration (Advanced) and is PCI-compliant.
* API credentials are active.
* The partner has completed Priceless Single Sign-On (SSO) onboarding. Priceless issues handoff tokens only to partners with an active SSO registration. Contact your API Integration Manager to complete SSO onboarding before using this flow.
* The partner backend is configured to call the catalog, user token, and cart endpoints.
* The partner app or website is configured to open WebView pages and handle return navigation.

The following sequence diagram shows API calls and redirect flow between partner surfaces and hosted checkout.

Diagram use-case-9

### Prerequisite: Fetch catalog metadata {#prerequisite-fetch-catalog-metadata}

These endpoints provide the categories, programs, and locations for your discovery page filters. Call them once during site setup, cache the responses, and refresh them when your catalog changes.


API Reference: `GET /categories`


API Reference: `GET /programs`


API Reference: `GET /locations`

<br />

### Step 1: Display products on your discovery page {#step-1-display-products-on-your-discovery-page}

Your discovery page displays products from the cached product catalog (fetched during the prerequisite). As cardholders interact with your filter controls, display the filtered results from your cached data according to your filtering logic.
For product tile design guidance, refer figma diagram [How to build product tiles](https://www.figma.com/design/nveD0DmZ4Z3p0rShgcBaAK/How-to-build-product-tiles?node-id=0-1&p=f&t=X7wyBcNF6F2H5SsG-0).


API Reference: `GET /products`

<br />

### Step 2: Show product details {#step-2-show-product-details}

When a cardholder selects a product, display cached product details. To reduce stale data risk, call `GET /products/{product_id}` at selection time.

For native PDP guidance, see [How to build a native product detail page](https://developer.mastercard.com/mastercard-benefits-and-experiences-portal/documentation/tutorials-and-guides/build-native-product-detail-page/index.md).


API Reference: `GET /products/{product_id}`

<br />

### Step 3: Create checkout session token {#step-3-create-checkout-session-token}

When redirecting to checkout, call the user token endpoint to create a temporary session token for authenticated continuation.


API Reference: `GET /user-tokens`

<br />

### Step 4: Prepare cart for hosted checkout {#step-4-prepare-cart-for-hosted-checkout}

With token and selected item ready, call the carts endpoint to add the item to the cart so checkout opens with purchase context already prepared.


API Reference: `GET /carts`

<br />

### Step 5: Open hosted checkout page in WebView {#step-5-open-hosted-checkout-page-in-webview}

Use the returned token to create the checkout URL and direct the cardholder to hosted checkout in WebView so they can complete payment.

For WebView and 3DS payment guidance, see [Webview and 3DS Payment Flow](https://developer.mastercard.com/mastercard-benefits-and-experiences-portal/documentation/use-cases/use-cases-10/index.md).

Example cart redirect URL pattern:

`https://demo.priceless.com/carts?access_token={accessToken}&partner_id={partnerId}`

Use this URL immediately after `POST /carts` returns a valid cart and the token from `POST /user-tokens` is still active.

### Step 6: Complete hosted checkout {#step-6-complete-hosted-checkout}

In hosted checkout, the cardholder reviews purchase details and completes payment while your app maintains return navigation and journey continuity.

### Step 7 (Optional): Display confirmation and live order status {#step-7-optional-display-confirmation-and-live-order-status}

After checkout completion, call the order status endpoint and display your confirmation view with order identifiers so the cardholder can track progress.


API Reference: `GET /orders/{order_id}/statuses`

<br />

### Step 8 (Optional): Enable post-purchase tracking from account area {#step-8-optional-enable-post-purchase-tracking-from-account-area}

In post-purchase flows, when the cardholder opens your account history page, call the order history endpoint and support reopening each order so the cardholder can review latest status details.


API Reference: `GET /order-histories`

<br />

### Error handling {#error-handling}

Use [Code and Formats](https://developer.mastercard.com/mastercard-benefits-and-experiences-portal/documentation/code-and-formats/index.md) as the source of truth for shared error payloads and reason codes.
Note: If checkout preparation fails, create a new token, add the item to the cart again, and then reopen hosted checkout.