API დოკუმენტაცია

Base URL: https://api.quickpay.ge/v1

What you can build

Quickpay is not just a card payment API. A single POST /v1/payments call covers six distinct payment flows — the gateway_slug field determines which flow the customer sees on the hosted payment page.

Quick Start

Get your first real payment working in three steps.

1. Get your API key — Dashboard → API Keys → copy your qpk_live_... key. Your key is tied to one Brand in your account.

2. Create a payment — call POST /v1/payments with your amount, description, and return URL. The response contains a payment_url.

curl -X POST https://api.quickpay.ge/v1/payments \
  -H "Authorization: Bearer qpk_live_..." \
  -H "Idempotency-Key: order-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 149.99,
    "currency": "GEL",
    "description": "Order #1234",
    "return_url": "https://yourshop.ge/thank-you"
  }'

3. Redirect & handle webhook — redirect your customer to the payment_url. When payment completes, Quickpay POSTs a payment.paid event to your Webhook URL (Dashboard → Brand Settings). See Webhooks.

Authentication

All API requests (except exchange rates) require a bearer token. Use your live key (qpk_live_...) for production and your test key (qpk_test_...) for development. Keys are brand-scoped — every key is tied to one Brand in your account.

Authorization: Bearer qpk_live_your_key_here

Rate limit: 100 requests per minute per API key. Rate-limit headers are returned on every response: X-RateLimit-Limit, X-RateLimit-Remaining.

Idempotency

Include an Idempotency-Key header on all POST requests to safely retry without double-charging. The same key returns the same payment response (HTTP 200). If you supply a key that was previously used with a *different amount or currency*, the API returns 409 Conflict.

Idempotency-Key: order-1234-attempt-1

Amounts & Currencies

All monetary values are decimal numbers. 5.00₾ = "amount": 5.00. Supported currencies: GEL · USD · EUR · GBP. When currency is omitted it defaults to GEL.

Errors

Errors always include a message field and a machine-readable error_code string. Validation errors (422) also include an errors object keyed by field name. See Error codes for the full list.

Official SDKs

Don't want to call the raw REST API by hand? These are thin, typed clients over this same API — no card data ever touches your server.

Platform Plugins

Building on WooCommerce, WHMCS, OpenCart, CS-Cart, PrestaShop, or Easy Digital Downloads? Skip the API entirely — install the matching plugin and configure it with an API key.

Plugins are downloaded from Dashboard → Integrations after registering, and support self-hosted one-click updates.

Create a payment

POST /v1/payments → Try in Playground

Creates a payment and returns a payment_url — redirect your customer there to complete checkout. Omit gateway_slug to let the customer choose their preferred gateway on the hosted payment page.

Body parameters

line_items[] object

custom_fields_schema[] object

Request example

curl -X POST https://api.quickpay.ge/v1/payments \
  -H "Authorization: Bearer qpk_live_..." \
  -H "Idempotency-Key: order-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 149.99,
    "currency": "GEL",
    "description": "Order #1234",
    "gateway_slug": "bog_card",
    "merchant_order_id": "ORD-1234",
    "customer_name": "Giorgi Beridze",
    "customer_email": "[email protected]",
    "return_url": "https://yourshop.ge/thank-you"
  }'

$response = Http::withToken('qpk_live_...')
    ->withHeaders(['Idempotency-Key' => 'order-1234'])
    ->post('https://api.quickpay.ge/v1/payments', [
        'amount'      => 149.99,
        'currency'    => 'GEL',
        'description' => 'Order #1234',
        'gateway_slug'=> 'bog_card',
        'return_url'  => 'https://yourshop.ge/thank-you',
    ]);
$paymentUrl = $response->json('payment_url');

const res = await fetch('https://api.quickpay.ge/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer qpk_live_...',
    'Idempotency-Key': 'order-1234',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 149.99, currency: 'GEL', description: 'Order #1234',
    gateway_slug: 'bog_card', return_url: 'https://yourshop.ge/thank-you',
  }),
});
const { payment_url } = await res.json();

import requests
r = requests.post(
    'https://api.quickpay.ge/v1/payments',
    headers={
        'Authorization': 'Bearer qpk_live_...',
        'Idempotency-Key': 'order-1234',
    },
    json={
        'amount': 149.99, 'currency': 'GEL', 'description': 'Order #1234',
        'gateway_slug': 'bog_card', 'return_url': 'https://yourshop.ge/thank-you',
    },
)
payment_url = r.json()['payment_url']

// 201 Created (200 on idempotency replay)
{
  "uuid": "018f2a3b-...",
  "merchant_order_id": "ORD-1234",
  "payment_url": "https://qpy.ge/pay/018f2a3b-...",
  "status": "pending",
  "amount": 149.99,
  "currency": "GEL",
  "discount_gel": null,
  "coupon_code": null,
  "redirect_url": null
}

Get a payment

GET /v1/payments/{uuid} → Try in Playground

Returns the full payment object.

Path parameters

// 200 OK
{
  "uuid": "018f2a3b-...",
  "merchant_order_id": "ORD-1234",
  "status": "paid",
  "amount": 149.99,
  "currency": "GEL",
  "description": "Order #1234",
  "customer_name": "Giorgi Beridze",
  "customer_email": "[email protected]",
  "gateway_order_id": "BOG-XYZ789",
  "surcharge": null,
  "coupon": null,
  "form_data": {},
  "line_items": null,
  "refunded_amount": 0,
  "refunds": [],
  "paid_at": "2026-05-16T10:23:00Z",
  "expires_at": null,
  "created_at": "2026-05-16T10:20:00Z"
}

Response fields

List payments

GET /v1/payments → Try in Playground

Returns a paginated list (20 per page) sorted newest first.

Query parameters

// 200 OK
{
  "data": [ { "...payment object..." } ],
  "meta": { "current_page": 1, "last_page": 5, "total": 92 }
}

Refund a payment

POST /v1/payments/{uuid}/refund → Try in Playground

Initiates a full or partial refund. Omit amount to refund the full remaining amount. Returns the updated payment object.

Path parameters

Body parameters

{ "amount": 50.00, "reason": "Customer requested partial refund" }

Returns 200 OK.

List products

GET /v1/products → Try in Playground

Returns a paginated list (20 per page) sorted newest first.

Query parameters

// 200 OK
{
  "data": [
    {
      "uuid": "018f...",
      "name_en": "Product Name",
      "name_ka": "პროდუქტის სახელი",
      "short_description_en": "...",
      "short_description_ka": "...",
      "price": 99.99,
      "compare_price": 129.99,
      "base_currency": "GEL",
      "accepted_currencies": ["GEL", "USD"],
      "sku": "SKU-001",
      "track_stock": false,
      "stock_quantity": null,
      "image_url": "https://...",
      "categories": ["clothing"],
      "custom_fields_schema": [],
      "is_active": true,
      "created_at": "2026-01-01T10:00:00Z",
      "updated_at": "2026-01-01T10:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "total": 3 }
}

Create a product

POST /v1/products → Try in Playground

At least one of name_en or name_ka is required.

Body parameters

Returns 201 Created.

Get a product

GET /v1/products/{uuid} → Try in Playground

Returns the full product object.

Path parameters

Returns 200 OK.

Response fields

Update a product

PUT /v1/products/{uuid} → Try in Playground

Partial update — include only the fields you want to change. Same field rules as create. Returns the full product object.

Path parameters

Returns 200 OK.

Delete a product

DELETE /v1/products/{uuid} → Try in Playground

Deletes the product.

Path parameters

// 200 OK
{ "deleted": true }

Create a checkout link

POST /v1/checkout-links → Try in Playground

Creates a reusable payment link. Provide either product_uuid (price comes from the product) or a fixed amount.

Body parameters

{
  "amount": 50.00,
  "currency_override": "GEL",
  "expires_at": "2026-12-31T23:59:59Z",
  "max_uses": 100
}

// 201 Created
{
  "uuid": "018f...",
  "url": "https://qpy.ge/p/abc123",
  "slug": "abc123",
  "product_uuid": null,
  "amount": 50.00,
  "currency": "GEL",
  "expires_at": "2026-12-31T23:59:59+00:00",
  "max_uses": 100,
  "is_active": true,
  "created_at": "2026-06-01T09:00:00+00:00"
}

Embed Button

Add a Quickpay checkout button to any HTML page with one script tag. Pass a checkout link UUID in data-checkout-link; the script renders a styled <a> immediately after the script tag, so right-click/open-in-new-tab still works.

<script src="https://qpy.ge/embed.js"
        data-checkout-link="YOUR_CHECKOUT_LINK_UUID"
        data-label="Buy Now"
        data-color="#2563eb">
</script>

List invoices

GET /v1/invoices → Try in Playground

Returns a paginated list (20 per page) sorted newest first.

Query parameters

Returns 200 OK.

Create an invoice

POST /v1/invoices → Try in Playground

Creates an invoice in draft status. Use Send invoice to email it. The response includes a payment_url the customer can use to pay online.

Body parameters

items[] object

{
  "customer_name": "Nino Kvaratskhelia",
  "customer_email": "[email protected]",
  "currency": "GEL",
  "due_at": "2026-07-01",
  "discount_type": "percent",
  "discount_value": 10,
  "items": [
    { "description": "Web design — 10 hours", "quantity": 10, "unit_price": 50.00 },
    { "description": "Hosting (monthly)", "quantity": 1, "unit_price": 15.00 }
  ]
}

// 201 Created
{
  "uuid": "018f...",
  "invoice_number": "INV-0001",
  "status": "draft",
  "currency": "GEL",
  "subtotal": 515.00,
  "discount_type": "percent",
  "discount_value": 10,
  "discount_amount": 51.50,
  "total": 463.50,
  "due_at": "2026-07-01",
  "payment_url": "https://qpy.ge/invoice/018f...",
  "items": [
    { "description": "Web design — 10 hours", "quantity": 10, "unit_price": 50.00, "line_total": 500.00 },
    { "description": "Hosting (monthly)", "quantity": 1, "unit_price": 15.00, "line_total": 15.00 }
  ]
}

Get an invoice

GET /v1/invoices/{uuid} → Try in Playground

Returns the full invoice object including payment_url, sent_at, viewed_at, and paid_at timestamps.

Path parameters

Returns 200 OK.

Response fields

Send an invoice

POST /v1/invoices/{uuid}/send → Try in Playground

Emails the invoice to the customer and transitions status to sent. Cannot be called when status is paid or cancelled.

Path parameters

// 200 OK
{
  "status": "sent",
  "sent_at": "2026-06-01T10:05:00+00:00",
  "email_delivered": true
}

List gateways

GET /v1/gateways → Try in Playground

Returns the active gateways for your brand — gateways with an active module subscription. Useful for populating a gateway selector in your own UI. Requires authentication but does not require a gateway license.

// 200 OK
{
  "gateways": [
    {
      "slug": "bog_card",
      "name": "BOG Card",
      "min_amount_gel": 0.5,
      "max_amount_gel": 50000,
      "brand_color": "#FF6600",
      "bg_color": "#FFF3E0",
      "icon_url": "https://cdn.quickpay.ge/gateways/bog.svg",
      "dark_icon_url": "https://cdn.quickpay.ge/gateways/bog-dark.svg"
    }
  ]
}

All supported gateways — static reference. GET /v1/gateways returns only the gateways with an active module subscription on your account.

Apple Pay and Google Pay are offered automatically by BOG and TBC on supported devices — no extra integration required.

List checkout templates

GET /v1/checkout-templates → Try in Playground

Returns the active checkout templates for your brand. Use the returned id as checkout_template_id when creating a payment. Requires authentication but does not require a gateway license.

// 200 OK
{
  "templates": [
    {
      "id": 1,
      "uuid": "018f...",
      "name": "Default",
      "is_default": true,
      "gateway_count": 3,
      "fields_count": 2
    }
  ]
}

Exchange rates

GET /v1/exchange-rates → Try in Playground

Public endpoint — no authentication required. Converts an amount between two currencies using live rates.

Query parameters

// 200 OK
{
  "from": "GEL",
  "to": "USD",
  "rate": 0.3676,
  "amount": 100,
  "converted": 36.76
}

Installments & BNPL

Trigger installment or BNPL checkout with a single POST /v1/payments — no extra API calls needed. Quickpay fetches available plans from the bank and displays them on the hosted payment page automatically.

Installment slugs: bog_installment · tbc_installment · credo_installment · flitt_installment — customer picks a repayment plan (3–36 months).

BNPL slugs: bog_bnpl (BOG "Part by Part") · flitt_bnpl — 0% interest split; the bank absorbs the financing cost.

1. Merchant passes an installment or BNPL gateway_slug in POST /v1/payments.
2. Customer lands on the hosted payment page — Quickpay fetches available plans live and displays them.
3. Customer selects a plan and completes checkout at the bank.
4. Merchant receives the full payment amount upfront.
5. Webhook fires payment.paid — identical to a card payment.

{
  "amount": 999.00,
  "currency": "GEL",
  "description": "MacBook Pro",
  "gateway_slug": "bog_installment",
  "return_url": "https://yourshop.ge/thank-you"
}

Plan availability and terms are fetched live from each bank's API and cached for 5 minutes. If the bank API is temporarily unavailable, the hosted page shows a graceful "currently unavailable" message.

Recurring Payments

Card-on-file and subscription billing using *_subscriptions gateway slugs. The customer completes the first payment on the hosted page, which charges and tokenises their card with the bank. Subsequent charges happen server-to-server with no customer interaction.

Available recurring slugs: bog_card_subscriptions · tbc_card_subscriptions · flitt_subscriptions · unipay_subscriptions · fastoo_subscriptions · paypal_subscriptions · liberty_card_subscriptions

Step 1   POST /v1/payments { gateway_slug: "bog_card_subscriptions", amount: 29.99 }
         → customer pays on the hosted page
         → payment.paid webhook fires with "subscription_token": "<uuid>"   ← save this

Step 2   POST /v1/payments/charge { subscription_token: "<uuid>", amount: 29.99 }
         → 202 Accepted
         → subscription.charged webhook on success (subscription.failed on failure)

Charge a subscription token

POST /v1/payments/charge → Try in Playground

Charges a stored subscription token server-to-server. The customer completed the first payment on the hosted page using a *_subscriptions slug, which tokenised their card with the bank.

Body parameters

// 202 Accepted
{
  "uuid": "018f...",
  "status": "pending",
  "amount": 29.99,
  "currency": "GEL",
  "subscription_token": "a1b2c3d4-...",
  "message": "Charge initiated. Final result will be delivered via webhook."
}

Webhooks

When a payment status changes, Quickpay sends a POST request to your Webhook URL (Dashboard → Brand Settings). Your endpoint must respond with HTTP 2xx within 30 seconds. Failed deliveries are retried up to 5 times with exponential back-off.

Payment events: payment.paid · payment.failed · payment.refunded · payment.partially_refunded · payment.refund_pending · payment.cancelled · payment.expired

Subscription events: subscription.charged · subscription.failed — fired by POST /v1/payments/charge.

Invoice events: invoice.paid — fired when an invoice is paid.

Lead events: lead.submitted — fired when a landing-page lead is captured.

{
  "event": "payment.paid",
  "uuid": "018f2a3b-...",
  "merchant_order_id": "ORD-1234",
  "status": "paid",
  "amount": 149.99,
  "currency": "GEL",
  "customer_name": "Giorgi Beridze",
  "customer_email": "[email protected]",
  "gateway_order_id": "BOG-XYZ789",
  "subscription_token": "a1b2c3d4-...",
  "paid_at": "2026-05-16T10:23:00Z",
  "created_at": "2026-05-16T10:20:00Z",
  "form_data": {},
  "metadata": {}
}

subscription_token is only present when the payment used a *_subscriptions gateway slug. Save it to use with POST /v1/payments/charge.

Signature verification

Every webhook request includes a QUICKPAY-SIGNATURE header. Always verify it to ensure the request is authentic and hasn't been tampered with.

QUICKPAY-SIGNATURE: t=1716123456,v1=abc123def456...

[$timestamp, $signature] = explode(",", $request->header("QUICKPAY-SIGNATURE"));
$timestamp = substr($timestamp, 2);   // strip "t="
$v1        = substr($signature, 3);   // strip "v1="

// Reject stale payloads (> 5 minutes)
if (abs(time() - (int)$timestamp) > 300) {
    abort(400, "Webhook timestamp too old");
}

$payload  = "{$timestamp}." . $request->getContent();
$expected = hash_hmac("sha256", $payload, $webhookSecret);

if (!hash_equals($expected, $v1)) {
    abort(400, "Invalid signature");
}

const crypto = require('crypto');
const [ts, sig] = req.headers['quickpay-signature'].split(',');
const timestamp = ts.replace('t=', '');
const v1 = sig.replace('v1=', '');

if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.status(400).send('Webhook timestamp too old');
}

const payload = `${timestamp}.${req.rawBody}`;
const expected = crypto.createHmac('sha256', webhookSecret).update(payload).digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) {
    return res.status(400).send('Invalid signature');
}

import hmac, hashlib, time

header = request.headers.get('QUICKPAY-SIGNATURE', '')
parts = dict(p.split('=', 1) for p in header.split(','))
timestamp, v1 = parts.get('t', ''), parts.get('v1', '')

if abs(time.time() - int(timestamp)) > 300:
    return 'Webhook timestamp too old', 400

payload = f"{timestamp}.{request.data.decode()}"
expected = hmac.new(webhook_secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

if not hmac.compare_digest(expected, v1):
    return 'Invalid signature', 400

Error codes

Every API error response includes a machine-readable error_code string alongside the human message. Switch on these stable codes instead of string-matching translated messages.

{ "error_code": "coupon_expired", "message": "This coupon has expired.", "errors": { "coupon_code": ["This coupon has expired."] } }

The errors object is only present on 422 validation responses.