Skip to main content
The Embedded flow renders Quidkey’s bank payment option next to your Stripe Payment Element. Buyers choose between card (Stripe) and bank transfer (Quidkey) without leaving your site. When the buyer picks one method, the other collapses.
This page is a quick orientation. If you’re not already on Stripe, start with the Redirect flow. The full Embedded walkthrough lives in the dedicated Embedded Flow guide.
This flow assumes you already run a Stripe Payment Element on your checkout. You’re adding Quidkey alongside it, not replacing it. No changes to your Stripe code are required.
Amounts are integer minor units. 2550 = €25.50. If your checkout already passes amounts in minor units, your existing amount handling carries over unchanged. See Amounts & Currencies.
Set test_transaction: true in the order while developing so no real money moves. See Testing.

​
How It Works

You create a payment request from your backend to get a short-lived payment_token, render the Quidkey iframe with that token next to your Stripe element, and wire up mutual exclusion so only one method is active at a time. When the buyer initiates payment, they’re sent to their bank to approve, and Quidkey confirms the result via webhook.

​
Create a Payment Request

Call POST /api/v1/embedded/payment-requests once the buyer has confirmed the final price. You get back a payment_token (valid for 15 minutes) to render in the iframe. 
curl -X POST 'https://core.quidkey.com/api/v1/embedded/payment-requests' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+4917646793347",
      "country": "DE"
    },
    "order": {
      "order_id": "ORD-123456",
      "amount": 2550,
      "currency": "EUR",
      "payment_reference": "Order3451",
      "locale": "en-GB",
      "test_transaction": true
    },
    "redirect_urls": {
      "success_url": "https://yoursite.com/success",
      "failure_url": "https://yoursite.com/failure"
    }
  }'
Response
{
  "success": true,
  "data": {
    "payment_token": "ptok_…",
    "expires_in": 900
  }
}
The response is enveloped: read payment_token and expires_in from data. Use the token to render the bank selection iframe.
Need to change the total after creating the request, for shipping or a discount code? Call PATCH /api/v1/embedded/payment-requests to update the amount or rewards before the buyer initiates payment. The full guide covers this in detail.

​
After Payment

When the buyer approves at their bank, Quidkey confirms the outcome with a signed webhook to your backend: this is the source of truth, not any browser redirect. Verify the signature, then fulfil on quidkey.payment_request.succeeded. The Embedded Flow after-payment guide covers handling postMessage events, signature verification, and processing fees end to end.

​
Full Integration Guide

This page is a quick orientation. Embedding the iframe, wiring up Stripe mutual exclusion, handling postMessage events, calling POST /api/v1/embedded/payment-initiation, and processing webhooks are all covered step by step in the dedicated Embedded Flow guide.

Embedded Flow Overview

The complete walkthrough: create, embed, mutual exclusion, and after-payment

Create a Payment Request

Authenticate, create the token, and update the amount or rewards

Embed the Checkout

Add the iframe and wire up Stripe mutual exclusion

After Payment

Handle webhooks, verify signatures, and process fees

​
Other Ways to Accept a Payment

Redirect (Pay by Bank)

No frontend checkout to build: create a payment and redirect the buyer

Hosted Checkout

Share a checkout link, no frontend code at all