> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quidkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedded Flow (with Stripe)

> Add Quidkey bank payments alongside your existing Stripe Payment Element

The Embedded Flow adds Quidkey's bank payment option alongside your existing Stripe Payment Element. Customers see both payment methods on your checkout page and choose between card payments (Stripe) or bank transfers (Quidkey), all without leaving your site.

<Note>
  This guide assumes you already have a **Stripe Payment Element** integrated on your checkout page. You're adding Quidkey alongside Stripe, not replacing it.
</Note>

<CardGroup cols={2}>
  <Card title="Create a Payment Request" icon="plus" href="/guides/embedded-flow/create">
    Authenticate and create a payment request to get a payment token
  </Card>

  <Card title="Embed the Checkout" icon="browser" href="/guides/embedded-flow/embed">
    Add the bank selection iframe and wire up Stripe mutual exclusion
  </Card>

  <Card title="After Payment" icon="chart-line" href="/guides/embedded-flow/after-payment">
    Handle webhooks, verify signatures, and process fees
  </Card>

  <Card title="API Playground" icon="flask" href="/api-reference/embedded/create-a-payment-request-and-return-a-payment_token-for-iframe-flow">
    Test creating a payment request in your browser. No setup required
  </Card>
</CardGroup>

## Prerequisites

* [ ] **Stripe Payment Element already integrated** on your checkout page
* [ ] Quidkey `client_id` and `client_secret` ([sign up](https://console.quidkey.com))
* [ ] HTTPS enabled on your checkout page

<Info>
  **No Stripe changes required.** Your existing Stripe integration stays exactly as it is. You're adding Quidkey alongside, not replacing anything.
</Info>

## When to Use the Embedded Flow

|                         | **Embedded Flow (with Stripe)**                              | **Payment Links**                                    |
| ----------------------- | ------------------------------------------------------------ | ---------------------------------------------------- |
| **Best for**            | Merchants with an existing Stripe checkout                   | Invoicing, ad-hoc payments, no-code scenarios        |
| **Integration effort**  | Embed iframe, handle postMessage events, route Pay button    | One API call to create a link, then share the URL    |
| **Customer experience** | Inline checkout on your site (Stripe + Quidkey side by side) | Quidkey-hosted checkout page                         |
| **Frontend code**       | HTML/JavaScript for iframe + Stripe mutual exclusion         | None                                                 |
| **Use case**            | E-commerce with Stripe, subscription platforms               | B2B invoices, service payments, cross-border pay-ins |

<Tip>
  **Need both?** You can use the Embedded Flow for your checkout page and Payment Links for invoice emails. They share the same backend API and webhook infrastructure.
</Tip>

## How It Works

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Customer
    participant Merchant as Merchant (frontend)
    participant Backend as Merchant (server)
    participant Quidkey
    Customer->>Merchant: Browse & fill checkout
    Merchant->>Backend: Finalise price
    Backend->>Quidkey: POST /embedded/payment-requests
    Quidkey-->>Backend: { payment_token }
    Backend-->>Merchant: Render checkout + inject iframe
    Merchant->>Quidkey: GET /embedded (iframe bootstrap)
    Quidkey-->>Merchant: Bank picker HTML
    opt Dynamic Updates (shipping, discounts, etc.)
        Customer->>Merchant: Change shipping/apply code
        Merchant->>Backend: Calculate new total
        Backend->>Quidkey: PATCH /embedded/payment-requests
        Quidkey-->>Backend: { updated amount/rewards }
        Backend-->>Merchant: Update confirmed
        Merchant->>Merchant: Refresh iframe & UI
    end
    Customer->>Merchant: Click preferred bank
    Merchant->>Merchant: postMessage { bankId, paymentScheme }
    Merchant->>Backend: POST /embedded/payment-initiation
    Backend->>Quidkey: POST /payment-initiations
    Quidkey-->>Backend: { payment_link }
    Backend-->>Merchant: { payment_link }
    Merchant-->>Customer: Redirect to bank (SCA)
    Customer->>Quidkey: Authenticate & approve payment
    alt Success
        Quidkey-->>Customer: Redirect to success_url
    else Failure / cancel
        Quidkey-->>Customer: Redirect to failure_url
    end
    Quidkey-->>Backend: Webhook notification
```

## Key Features

* **Works alongside Stripe**: customers choose between card (Stripe) or bank transfer (Quidkey) on the same checkout page
* **Mutual exclusion**: when a customer selects Quidkey, the Stripe Payment Element collapses, and vice versa
* **Bank prediction**: Quidkey automatically predicts and pre-selects the customer's bank
* **Multiple payment schemes**: SEPA, Faster Payments, Multibanco, and more supported automatically
* **Dynamic amounts**: update the payment amount after creation (e.g., shipping costs, discounts)
* **Dynamic height**: iframe adjusts height automatically based on available payment methods
* **Rewards**: optional loyalty rewards displayed to customers during checkout
* **Per-payment webhook routing**: fan a payment's webhooks out to one or more named endpoints, each with its own signing secret and test/live scope, ideal for platforms sending on behalf of multiple businesses

## Next Steps

<Steps>
  <Step title="Create a payment request">
    Follow the [Create a Payment Request](/guides/embedded-flow/create) guide to authenticate and get a payment token.
  </Step>

  <Step title="Embed the checkout">
    Learn how to [embed the bank selection iframe](/guides/embedded-flow/embed) on your checkout page, including Stripe mutual exclusion.
  </Step>

  <Step title="Handle post-payment">
    Set up [webhooks and fee processing](/guides/embedded-flow/after-payment) to complete your integration.
  </Step>
</Steps>