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

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

This use case shows how to combine partner-native product discovery (catalogue tiles) with a Priceless-hosted product detail page (PDP) and checkout. Your app or site owns discovery and redirect steps, while Priceless-hosted pages handle content description, cart, and payment.
Note: Single Sign-On (SSO) is optional for this flow. PCI compliance is required only if you implement SSO. 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 provides a branded discovery experience and then directs the cardholder to a Priceless WebView for description reading and checkout.

**Goal:** Enable cardholders to discover products in partner UI and complete purchase in a secure Priceless-hosted flow.

**Main actors:** Cardholder, Partner app or website, Partner backend, Priceless APIs, Priceless-hosted product detail and checkout pages.

**Preconditions:**

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

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

Diagram use-case-8

### 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.

In this flow, you do not build the product detail page natively. The cardholder is always redirected to the Priceless-hosted product detail page, which handles both standard and punchout products. You do not need to check `isTilePunchout`.

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/{product_id}`

<br />

### Step 3 (Optional): Create secure handoff token (with SSO) {#step-3-optional-create-secure-handoff-token-with-sso}

If you implement Single Sign-On (SSO), call the user token endpoint to generate a temporary access token for authenticated continuation on Priceless-hosted pages. Skip this step if you do not implement SSO.


API Reference: `GET /user-tokens`

Note: For WebView handoff issues, generate a fresh token with `POST /user-tokens` and rebuild the handoff URL before retrying. Tokens are short-lived and single-use for successful WebView URL opening.

<br />

### Step 4: Open the Priceless-hosted PDP {#step-4-open-the-priceless-hosted-pdp}

Direct the cardholder to the Priceless-hosted PDP in WebView so they can continue checkout without restarting discovery. The URL depends on whether you implement SSO.

* **Without SSO:** open the Priceless PDP URL directly.

  `https://demo.priceless.com/p/219122/s/25189`
* **With SSO:** use the selected product identifier and the returned `accessToken` to build the handoff URL.

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

  Use this URL immediately after `POST /user-tokens` returns a valid token.

In WebView, the cardholder completes cart and payment on the Priceless-hosted pages while your app maintains the journey context and return navigation.

### Step 5 (Optional): Display confirmation and live order status {#step-5-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 from your app or site.

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

### Step 6 (Optional): Enable post-purchase tracking from account area {#step-6-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.
Note: Order history requires Single Sign-On (SSO). `GET /order-histories` needs the cardholder UUID, which only SSO provides.
API Reference: `GET /order-histories`

### 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.