Create a Payment Request

Create a payment request to get a payment_token that you’ll use to render the bank selection iframe on your checkout page.

Prerequisites

A Quidkey merchant account with client_id and client_secret
HTTPS enabled on your checkout page

Sign Up for Credentials

Create your merchant account to get your client_id and client_secret.

Step 1: Authenticate

Get an access token using your credentials. The token is valid for 15 minutes.

curl -X POST 'https://core.quidkey.com/api/v1/oauth2/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'

const response = await fetch('https://core.quidkey.com/api/v1/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: process.env.QUIDKEY_CLIENT_ID,
    client_secret: process.env.QUIDKEY_CLIENT_SECRET
  })
});

const { access_token, refresh_token, expires_in } = await response.json();

import os, requests

response = requests.post(
    'https://core.quidkey.com/api/v1/oauth2/token',
    json={
        'client_id': os.getenv('QUIDKEY_CLIENT_ID'),
        'client_secret': os.getenv('QUIDKEY_CLIENT_SECRET')
    }
)

data = response.json()
access_token = data['access_token']

What you’ll receive:

access_token: include as Authorization: Bearer <token> in subsequent calls
refresh_token: call /oauth2/refresh to get a new access token without re-posting credentials
expires_in: token validity in seconds (typically 900 = 15 minutes)

See the Authentication API reference for complete details and interactive playground.

Step 2: Create a Payment Request

Use the access token to create a payment request. This should be called once the customer has confirmed the final price at checkout.

Create this request after the customer confirms price and options. The payment token has a 15-minute TTL.

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": "Order #3451",
      "locale": "en-GB",
      "test_transaction": true
    },
    "redirect_urls": {
      "success_url": "https://yoursite.com/success",
      "failure_url": "https://yoursite.com/failure"
    }
  }'

const response = await fetch('https://core.quidkey.com/api/v1/embedded/payment-requests', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer: {
      name: 'John Doe',
      email: 'john@example.com',
      phone: '+4917646793347',
      country: 'DE'
    },
    order: {
      order_id: 'ORD-123456',
      amount: 2550,       // €25.50 in cents
      currency: 'EUR',
      payment_reference: 'Order #3451',
      locale: 'en-GB',
      test_transaction: true
    },
    redirect_urls: {
      success_url: 'https://yoursite.com/success',
      failure_url: 'https://yoursite.com/failure'
    }
  })
});

const { payment_token, expires_in } = await response.json();
console.log('Payment token:', payment_token);

response = requests.post(
    'https://core.quidkey.com/api/v1/embedded/payment-requests',
    headers={'Authorization': f'Bearer {access_token}'},
    json={
        'customer': {
            'name': 'John Doe',
            'email': 'john@example.com',
            'phone': '+4917646793347',
            'country': 'DE'
        },
        'order': {
            'order_id': 'ORD-123456',
            'amount': 2550,       # €25.50 in cents
            'currency': 'EUR',
            'payment_reference': 'Order #3451',
            'locale': 'en-GB',
            'test_transaction': True
        },
        'redirect_urls': {
            'success_url': 'https://yoursite.com/success',
            'failure_url': 'https://yoursite.com/failure'
        }
    }
)

data = response.json()
payment_token = data['payment_token']

You’ll receive a payment_token (valid for 15 minutes) to embed in your iframe. See the Create Payment Request API for the complete specification.

Request Body Reference

Field	Type	Required	Description
`customer.name`	string	Yes	Customer’s full name
`customer.email`	string	Yes	Customer’s email address
`customer.phone`	string	Yes	E.164 format phone number
`customer.country`	string	Yes	ISO 3166-1 alpha-2 country code
`order.amount`	integer	Yes	Amount in minor units (cents). `2550` = €25.50
`order.currency`	string	Yes	ISO 4217 currency code
`order.payment_reference`	string	Yes	Reference shown on bank statement
`order.order_id`	string	No	Your internal order identifier
`order.locale`	string	No	BCP-47 locale tag. Default: `en`
`order.test_transaction`	boolean	No	Set `true` for development testing
`order.rewards`	object	No	Optional loyalty rewards (see below)
`redirect_urls.success_url`	string	Yes	Where to redirect after successful payment
`redirect_urls.failure_url`	string	Yes	Where to redirect after failed/cancelled payment
`webhook_endpoints`	string[]	No	Route (fan out) this payment’s webhooks to up to 10 named endpoints. See below.

Amount format: Use minor units (cents). 1000 = €10.00, 2550 = €25.50. This matches Stripe’s format exactly.

Rewards (optional)

Include a rewards object to display loyalty rewards during checkout:

{
  "rewards": {
    "extra_rewards": 150,
    "total_rewards": 300,
    "description": "Loyalty bonus + base rewards"
  }
}

extra_rewards: reward points for this transaction
total_rewards: total points customer will receive (optional)
description: text describing the reward (max 255 characters, optional)

Rewards are distributed only on successful payment completion via webhook.

Webhook routing (optional)

Leave this unset for normal use. When you omit webhook_endpoints, the payment’s webhooks follow your merchant resolution order: your default webhook_url, then your default endpoint, then your single active endpoint. Most integrations never set this field.To send a payment’s webhooks to specific named endpoints instead (for platforms paying out on behalf of several businesses), add webhook_endpoints to the request body with up to 10 endpoint names:

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": "Order #3451" },
    "redirect_urls": { "success_url": "https://yoursite.com/success", "failure_url": "https://yoursite.com/failure" },
    "webhook_endpoints": ["wizzair-prod"]
  }'

The webhook is fanned out to every named endpoint, each signed with its own secret. A reference that is unknown, disabled, not owned by you, or whose test/live scope does not match the payment returns 400 UNKNOWN_WEBHOOK_ENDPOINT, and the payment is not created.

Update a Payment Request (Optional)

After creating a payment request, you can update the amount and/or rewards before the customer initiates payment with their bank. This is useful for dynamic shipping costs, discount codes, or cart modifications.

curl -X PATCH 'https://core.quidkey.com/api/v1/embedded/payment-requests' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_token": "ptok_efghijklm...",
    "amount": 2750
  }'

const response = await fetch('https://core.quidkey.com/api/v1/embedded/payment-requests', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_token: paymentToken,
    amount: originalAmount + shippingCost
  })
});

Amount updates are only allowed while payment status is pending
Once the customer clicks a bank and starts payment, only rewards can be updated
Amount updates are blocked after payment initiation

Next Steps

Embed the Checkout

Add the bank selection iframe to your checkout page

After Payment

Handle webhooks, verify signatures, and process fees

API Reference

Full endpoint documentation with interactive playground

Embedded Flow Overview

Back to the overview and integration flow diagram

Getting started

Shopify

Embedded Flow (with Stripe)

Payment Links

Payouts

Create a Payment Request

Prerequisites

Sign Up for Credentials

Step 1: Authenticate

Step 2: Create a Payment Request

Request Body Reference

Update a Payment Request (Optional)

Next Steps

Embed the Checkout

After Payment

API Reference

Embedded Flow Overview

​Prerequisites

Sign Up for Credentials

​Step 1: Authenticate

​Step 2: Create a Payment Request

​Request Body Reference

​Update a Payment Request (Optional)

​Next Steps

Embed the Checkout

After Payment

API Reference

Embedded Flow Overview

Prerequisites

Step 1: Authenticate

Step 2: Create a Payment Request

Request Body Reference

Update a Payment Request (Optional)

Next Steps