# Webview and 3DS Payment Flow
source: https://developer.mastercard.com/mastercard-benefits-and-experiences-portal/documentation/use-cases/use-cases-10/index.md

## Webview and 3DS Payment Flow {#webview-and-3ds-payment-flow}

3DS verification is supported for any type of Priceless Platform Integration model. In this flow, your app continues the standard purchase journey and opens a secure verification screen only when a payment needs additional cardholder verification. The cardholder completes One Time Password (OTP) or Two Factor Authentication (2FA), returns to your app, and then sees the final order outcome.

**Context:** Partner app or website handles the full shopping journey and opens a 3DS WebView only when payment verification is required.

**Goal:** Complete secure 3DS verification and return cardholders to your app or website with a clear success or failure outcome.

**Main actors:** Cardholder, Partner app or website, Mastercard.

**Persona:** External partner developer implementing app or web checkout.

### Choose your implementation flow {#choose-your-implementation-flow}

Complete the purchase flow that matches your integration model before implementing the 3DS steps in this article:

* [Native API: Checkout Integrated](https://developer.mastercard.com/mastercard-benefits-and-experiences-portal/documentation/use-cases/use-cases-7/index.md)
* [Hybrid API Integration: Simplified Flow](https://developer.mastercard.com/mastercard-benefits-and-experiences-portal/documentation/use-cases/use-cases-8/index.md)
* [Hybrid API Integration: Advanced](https://developer.mastercard.com/mastercard-benefits-and-experiences-portal/documentation/use-cases/use-cases-9/index.md)

**Preconditions:**

* Your integration is enabled for a Priceless Platform Integration model.
* API credentials are active.
* Your app or site can open and close WebView pages and handle return navigation.
* The purchase flow for your selected integration model can place an order with `POST /orders`.

The following sequence diagram shows the 3DS-specific flow after order placement. It uses the Native API: Checkout Integrated flow as an example. The same 3DS steps apply to the Hybrid API Integration: Simplified Flow and Hybrid API Integration: Advanced flows.

Diagram use-case-10

### Step 1: Place order and detect 3DS requirement {#step-1-place-order-and-detect-3ds-requirement}

Place the order by calling `POST /orders` through your selected integration model.

After you receive the response, check these two fields:

* `threeDSData.threeDSRequired`
* `threeDSData.redirectUrl`

If `threeDSData.threeDSRequired` is `true` and `threeDSData.redirectUrl` is present, continue to Step 2 in this article.

If `threeDSData.threeDSRequired` is `false`, no extra verification page is needed. Continue with your standard post-order flow.

#### Key parameters and fields {#key-parameters-and-fields}

* `data.threeDSData.threeDSRequired`: Indicates whether cardholder verification is required.
* `data.threeDSData.redirectUrl`: URL to open in WebView when 3DS verification is required.
* `data.nextStep`: Next-step guidance returned by the order response.
* `order_id`: Identifier used later to retrieve final status.


API Reference: `GET /orders`

### Step 2: Open WebView for cardholder verification {#step-2-open-webview-for-cardholder-verification}

Open the Priceless redirect URL from the response in your in-app WebView (or browser surface if your experience uses web navigation). Show a clear verification message before opening the verification page.

Example response URL pattern:
`https://{host}/order/3dsInit/{session_id}/{verification_token}/{signature}`

Check these components in `data.threeDSData.redirectUrl`:

* `https://{host}`: Secure URL returned by the API.
* `/order/3dsInit/`: 3DS verification path prefix.
* `{session_id}`: Session identifier for the current verification flow.
* `{verification_token}`: One-time verification token.
* `{signature}`: Integrity value for the verification URL.

Use the URL exactly as returned in `data.threeDSData.redirectUrl`. Do not edit, decode, or rebuild any part of it.

### Step 3: Cardholder completes 3DS verification {#step-3-cardholder-completes-3ds-verification}

The cardholder completes the OTP or 2FA prompt in WebView. Keep the session active and avoid closing the screen while verification is in progress.

### Step 4: Show outcome and refresh order status {#step-4-show-outcome-and-refresh-order-status}

After verification completes, show the result in WebView, close the WebView when appropriate, and fetch final order status for your confirmation experience.

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

### Error handling and retry guidance {#error-handling-and-retry-guidance}

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 response codes, reason codes, and error payload formats.

For this 3DS flow, use the following retry guidance:

* If WebView fails to open `data.threeDSData.redirectUrl`, ask the cardholder to retry once and then restart from `POST /orders`.
* If verification times out, let the cardholder retry verification from the same session when possible.
* If status is still pending, call `GET /orders/{order_id}/statuses` at regular intervals (for example, every 5-10 seconds) until you get a final status or reach your app timeout limit.

Use this guide for common 3DS outcomes:

|               What happened                |                  What it means                  |  Platform status   | Check in Order Status API | Shows in Order History API |                                What to do next                                |
|--------------------------------------------|-------------------------------------------------|--------------------|---------------------------|----------------------------|-------------------------------------------------------------------------------|
| Verification is still in progress          | Payment verification has not finished yet.      | `PENDING_CHECKOUT` | Yes                       | No                         | Keep checking status until a final result is available.                       |
| Verification completed successfully        | The order is placed.                            | `PLACED`           | Yes                       | Yes                        | Show confirmation and order details.                                          |
| OTP expired                                | Verification failed and the order is cancelled. | `CANCELLED`        | Yes                       | No                         | Ask the cardholder to start checkout again.                                   |
| Verification session expired               | Verification failed and the order is cancelled. | `CANCELLED`        | Yes                       | No                         | Ask the cardholder to restart checkout and verify again.                      |
| Cardholder cancelled verification          | Verification failed and the order is cancelled. | `CANCELLED`        | Yes                       | No                         | Let the cardholder retry when ready.                                          |
| Cardholder closed WebView before finishing | Verification was not completed.                 | `PENDING_CHECKOUT` | Yes                       | No                         | Reopen WebView from the same flow if still valid, otherwise restart checkout. |

Note: Treat `GET /orders/{order_id}/statuses` as the source of truth for final purchase outcome after any 3DS verification step.