Skip to main content
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"
  }'
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"
    }
  }'
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

FieldTypeRequiredDescription
customer.namestringYesCustomer’s full name
customer.emailstringYesCustomer’s email address
customer.phonestringYesE.164 format phone number
customer.countrystringYesISO 3166-1 alpha-2 country code
order.amountintegerYesAmount in minor units (cents). 2550 = €25.50
order.currencystringYesISO 4217 currency code
order.payment_referencestringYesReference shown on bank statement
order.order_idstringNoYour internal order identifier
order.localestringNoBCP-47 locale tag. Default: en
order.test_transactionbooleanNoSet true for development testing
order.rewardsobjectNoOptional loyalty rewards (see below)
redirect_urls.success_urlstringYesWhere to redirect after successful payment
redirect_urls.failure_urlstringYesWhere to redirect after failed/cancelled payment
Amount format: Use minor units (cents). 1000 = €10.00, 2550 = €25.50. This matches Stripe’s format exactly.
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.

​
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
  }'
  • 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