API Documentation

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.

MCP Server (for AI Agents)

Building with an AI coding agent (Claude, Cursor, and others)? https://mcp.quickpay.ge is a public, no-auth Model Context Protocol server — a live reference your agent can query directly instead of copy-pasting these docs into its context.

{
  "mcpServers": {
    "quickpay": {
      "url": "https://mcp.quickpay.ge"
    }
  }
}

All tools are read-only except create-test-payment, which only ever creates sandbox data behind a qpk_test_... key — no real money moves through this server. Looking for an AI agent that can manage your live account (create payments, issue refunds, update products)? That's a separate OAuth-authenticated server — see Dashboard → Integrations → Connected AI Apps.

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 product_uuid (price comes from the product), a fixed amount, or neither for a variable-amount link — the customer picks/enters the amount on the payment page (donations, tips, pay-what-you-want).

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.

Get installment plans

GET /v1/installment-plans/{gateway_slug} → Try in Playground

Fetches real installment/BNPL plan numbers for a gateway before redirecting the customer — same live calculator POST /v1/payments uses internally on the hosted page, exposed directly for integrators who need to show plan terms on their own checkout UI first.

Path parameters

Query parameters

// 200 OK
{
  "supports_installments": true,
  "plans": [
    { "months": 3, "monthly_payment": 50.33, "total": 150.99, "discount_code": "STANDARD", "label": "3 თვე — 50.33 ₾/თვე" }
  ]
}

Requires an active gateway license the same way POST /v1/payments does — the license check is domain-wide, not per gateway.

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 · dodo_payments_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."
}

Zero-Amount Tokenization

Save a customer's card on file without charging anything — useful for signing a customer up before their first real charge is known (e.g. a free trial, or a plan the customer picks later). Pass tokenize_only: true on POST /v1/payments with a *_subscriptions gateway_slug. amount is forced to 0 server-side regardless of what you post.

{
  "gateway_slug": "tbc_card_subscriptions",
  "tokenize_only": true,
  "customer_email": "[email protected]"
}

Supported gateways: bog_card_subscriptions · tbc_card_subscriptions · flitt_subscriptions · unipay_subscriptions · fastoo_subscriptions · liberty_card_subscriptions · dodo_payments_subscriptions. paypal_subscriptions is plan/billing-agreement based, not a generic saved-card token, so it always returns 422 tokenize_only_gateway_unsupported.

The customer completes the save-card step on the hosted page exactly like a normal first *_subscriptions payment. Once the bank confirms the card is saved, the payment resolves to status: "paid" (amount 0) and payment.paid fires on the webhook with a subscription_token — use it with POST /v1/payments/charge for the customer's first real charge.

Managing subscriptions

Full lifecycle management for CustomerSubscriptions beyond the basic recurring-charge flow above — list/filter, merchant-initiated creation, cancel (immediate or at period end), pause/resume, reactivate, and a paginated audit trail. See also Zero-Amount Tokenization for saving a card without a subscription.

List subscriptions

GET /v1/subscriptions → Try in Playground

Lists your brand's recurring subscriptions, newest first.

Query parameters

// 200 OK
{
  "data": [
    {
      "uuid": "018f...",
      "plan_uuid": "018f...",
      "customer_id": 42,
      "customer_name": "Giorgi Beridze",
      "customer_email": "[email protected]",
      "customer_phone": "+995555000000",
      "amount": 29.99,
      "currency": "GEL",
      "status": "active",
      "gateway_slug": "bog_card_subscriptions",
      "billing_interval_unit": "month",
      "billing_interval_count": 1,
      "billing_anchor_day": null,
      "current_period_start": "2026-08-16T10:20:00Z",
      "current_period_end": "2026-09-16T10:20:00Z",
      "next_billing_date": "2026-09-16T10:20:00Z",
      "last_charge_at": "2026-08-16T10:20:00Z",
      "cancelled_at": null,
      "created_at": "2026-05-16T10:20:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 20, "total": 1 }
}

Create a subscription (merchant-initiated)

POST /v1/subscriptions → Try in Playground

Starts a recurring subscription for a customer who already has a saved payment method — e.g. a phone-order subscription. This never collects card details itself: create the payment method first with Add a payment method. No initial charge is made; the first charge happens at the plan's next period end via the normal renewal cycle, exactly like a subscription created through the hosted checkout.

Body parameters

// 201 Created
{
  "uuid": "018f...",
  "plan_uuid": "018f...",
  "customer_id": 42,
  "status": "active",
  "amount": 29.99,
  "currency": "GEL",
  "gateway_slug": "bog_card_subscriptions",
  "current_period_start": "2026-09-16T10:20:00Z",
  "current_period_end": "2026-10-16T10:20:00Z"
}

Get a subscription

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

Returns a single subscription by UUID.

Path parameters

Returns 200 OK.

List subscription events

GET /v1/subscriptions/{uuid}/events → Try in Playground

The subscription's full audit trail, paginated, newest first — every charge, failure, cancellation, pause/resume, plan change, payment-method update, and reactivation.

Path parameters

// 200 OK
{
  "data": [
    {
      "id": 501,
      "event_type": "plan_changed",
      "actor_type": "merchant",
      "actor_id": 7,
      "payload": { "from_plan_id": 12, "to_plan_id": 13, "mode": "immediate", "amount": 10.0 },
      "created_at": "2026-09-01T09:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 20, "total": 1 }
}

Cancel a subscription

POST /v1/subscriptions/{uuid}/cancel → Try in Playground

Cancels a subscription, immediately by default.

Path parameters

Body parameters

Returns 200 OK.

Reactivate a subscription

POST /v1/subscriptions/{uuid}/reactivate → Try in Playground

Undoes a cancellation — moves a cancelled, past_due, or pending_cancellation subscription back to active.

Path parameters

Returns 200 OK.

Pause a subscription

POST /v1/subscriptions/{uuid}/pause → Try in Playground

Pauses an active subscription — no further charges happen while paused.

Path parameters

Body parameters

Returns 200 OK.

Resume a subscription

POST /v1/subscriptions/{uuid}/resume → Try in Playground

Resumes a paused subscription back to active.

Path parameters

Returns 200 OK.

Plan changes & payment methods on file

Move a subscription onto a different SubscriptionPlan with configurable proration, or hand the customer a hosted link to update their card or manage everything themselves.

Get an update-card link

POST /v1/subscriptions/{uuid}/update-payment-method → Try in Playground

Mints a one-time hosted link that walks the customer through re-entering their card on the bank's own checkout page. On completion, the subscription is repointed at the newly-saved CustomerPaymentMethod.

Path parameters

// 200 OK
{
  "update_url": "https://qpy.ge/update-card/eyJpdiI6...",
  "expires_at": "2026-09-18T10:20:00Z"
}

Preview a plan change

POST /v1/subscriptions/{uuid}/preview-plan-change → Try in Playground

Computes what Change plan would charge or credit, without changing anything — build an upgrade/downgrade confirmation screen against this.

Path parameters

Body parameters

// 200 OK
{
  "mode": "immediate",
  "amount": 10.0,
  "currency": "GEL",
  "from_plan_uuid": "018f...",
  "to_plan_uuid": "018f...",
  "remaining_days": 15,
  "total_days": 30
}

Change plan

POST /v1/subscriptions/{uuid}/change-plan → Try in Playground

Moves a subscription onto a different plan. immediate mode charges/credits the prorated difference right away; deferred folds it into the next renewal charge; none takes effect at the next renewal with no math. Every change writes its own auditable proration record regardless of mode.

Path parameters

Body parameters

// 200 OK
{
  "subscription": { "uuid": "018f...", "status": "active", "amount": 39.99 },
  "proration": {
    "id": 501,
    "mode": "immediate",
    "amount": 10.0,
    "from_plan_id": 12,
    "to_plan_id": 13,
    "applied_at": "2026-09-01T09:00:00Z",
    "applied_to_payment_id": 9001,
    "created_at": "2026-09-01T09:00:00Z"
  }
}

Get a hosted portal link

POST /v1/subscriptions/{uuid}/portal-session → Try in Playground

Mints a qpy.ge/manage/{token} hosted link — point your own "Manage Subscription" button at the returned url (Hybrid tier) rather than building subscription-management UI yourself.

Path parameters

Body parameters

// 201 Created
{
  "url": "https://qpy.ge/manage/9f8c...",
  "scope": "subscription",
  "expires_at": "2026-10-16T10:20:00Z"
}

Recipes: letting a customer manage their own subscription

Every *_subscriptions gateway requires the customer to be able to view and cancel their own subscription — this traces back to a National Bank of Georgia rule on recurring payments, and every Quickpay-hosted subscription notice email already links to it. You have two ways to offer this, and you can mix them per subscription — nothing below needs picking once for the whole integration.

Recipe A — use the hosted portal

Mint a signed link and point a "Manage Subscription" button at it. Quickpay renders the whole page — plan, next billing date, charge history, and cancel/update-card actions — themed with your brand's logo and colors. You never see the customer's card details or session state.

1. Call POST /v1/subscriptions/{uuid}/portal-session (see Plan changes & payment methods on file above) whenever you want to send the customer a management link — from your own dashboard, a support macro, an SMS, or a "Manage my subscription" email you send yourself.
2. Pass "scope": "subscription" (default) for a link scoped to just that one subscription, or "scope": "all" to cover every subscription sharing that customer's email on your brand — useful for a customer with more than one active subscription.
3. The response is { "url": "https://qpy.ge/manage/<token>", "expires_at": "..." }. The link is multi-use until it expires (ttl_days, default 30) — send the same one in a follow-up reminder rather than minting a new one each time.
4. Nothing else to build: the page itself handles cancel and "update payment method" (which redirects into the same zero-amount re-tokenization flow as Zero-Amount Tokenization).

POST /v1/subscriptions/f47ac10b-58cc-4372-a567-0e02b2c3d479/portal-session
{
  "scope": "subscription",
  "ttl_days": 30
}

→ 201 Created
{
  "url": "https://qpy.ge/manage/qpm_9f8e7d6c5b4a...",
  "scope": "subscription",
  "expires_at": "2026-10-17T09:00:00Z"
}

Recipe B — build your own subscription portal

For a merchant with an existing logged-in customer dashboard who wants subscription management to feel native — same layout, same session, no redirect to a Quickpay-hosted page. Call the API directly for every action; nothing is hosted for you.

1. On your customer's account/orders page, call GET /v1/subscriptions?customer_email=... (or customer_id) to list what they have. Each row includes status, amount, current_period_end, and the plan.
2. For the detail view, GET /v1/subscriptions/{uuid} for the current state and GET /v1/subscriptions/{uuid}/events for the paginated audit trail (created, charged, charge_failed, cancelled, paused, resumed, plan_changed, payment_method_updated) — enough to render a full timeline without your own event log.
3. "Cancel" → POST /v1/subscriptions/{uuid}/cancel. Pass "at_period_end": true for a "cancel at the end of the current billing period" option (access continues, no further charge) instead of immediate cancellation.
4. "Pause" / "Resume" → POST /v1/subscriptions/{uuid}/pause (optionally with resumes_at for a scheduled auto-resume) and POST /v1/subscriptions/{uuid}/resume.
5. "Change plan" → POST /v1/subscriptions/{uuid}/preview-plan-change to show the customer the exact prorated amount before they confirm, then POST /v1/subscriptions/{uuid}/change-plan to apply it.
6. "Update card" → you still don't re-implement tokenization yourself: call POST /v1/subscriptions/{uuid}/update-payment-method, which returns a one-time hosted redirect URL to the bank's own card-entry page. Send the customer there (a new tab or a WebView), and the card is vaulted on return — same mechanism recipe A's portal uses internally.

A SubscriptionPlan is a versioned billing definition — amount, interval, trial, proration default — that a subscription is created onto or moved between. Editing a plan never rewrites subscriptions already on it; it creates a new version and archives the old one.

List subscription plans

GET /v1/subscription-plans → Try in Playground

Lists your brand's subscription plans, newest first.

Query parameters

Returns 200 OK.

Create a subscription plan

POST /v1/subscription-plans → Try in Playground

Creates a versioned billing plan that subscriptions can be created or moved onto.

Body parameters

// 201 Created
{
  "uuid": "018f...",
  "product_id": null,
  "name": "Pro monthly",
  "amount": 29.99,
  "currency": "GEL",
  "billing_interval_unit": "month",
  "billing_interval_count": 1,
  "status": "active",
  "version": 1
}

Get a subscription plan

GET /v1/subscription-plans/{uuid} → Try in Playground

Returns a single subscription plan by UUID.

Path parameters

Returns 200 OK.

Edit a subscription plan

PATCH /v1/subscription-plans/{uuid} → Try in Playground

"Editing" a plan never mutates it in place — it creates a new version (a fresh UUID, version incremented) and archives this one, so subscriptions already on it keep their own billing snapshot untouched. Send only the fields you want to change; the rest carry over from the current version.

Path parameters

Body parameters

Returns 201 Created.

Archive a subscription plan

DELETE /v1/subscription-plans/{uuid} → Try in Playground

Archives a plan — it stops appearing as a choice for new subscriptions or plan changes, but existing subscriptions on it are untouched (they keep their own billing snapshot). Never actually deletes the row.

Path parameters

Returns 200 OK.

A CustomerPaymentMethod is a reusable, vaulted saved card — decoupled from any one subscription, so a customer can hold several and reuse one across subscriptions. Adding one reuses the same zero-amount tokenization mechanism as Zero-Amount Tokenization.

List a customer's payment methods

GET /v1/customers/{id}/payment-methods → Try in Playground

Lists the saved, reusable payment methods on file for one customer.

Path parameters

Query parameters

// 200 OK
{
  "data": [
    {
      "uuid": "018f...",
      "customer_id": 42,
      "gateway_slug": "bog_card_subscriptions",
      "card_brand": "visa",
      "card_last4": "4242",
      "card_exp_month": 12,
      "card_exp_year": 2029,
      "is_default": true,
      "status": "active",
      "created_at": "2026-05-16T10:20:00Z"
    }
  ]
}

Add a payment method

POST /v1/customers/{id}/payment-methods → Try in Playground

Starts a card-save flow for a customer — reuses the same zero-amount tokenize_only mechanism as Create a payment, just scoped to a customer instead of a subscription. Redirect the customer to the returned payment_url to complete it on the gateway's own hosted page; the new CustomerPaymentMethod appears once they finish.

Path parameters

Body parameters

// 201 Created
{
  "uuid": "018f...",
  "payment_url": "https://qpy.ge/pay/018f...",
  "status": "pending"
}

Remove a payment method

DELETE /v1/payment-methods/{uuid} → Try in Playground

Soft-removes a saved payment method (status becomes removed) — never a hard delete, so it stays visible on past subscription/event history.

Path parameters

Returns 200 OK.

Set a payment method as default

POST /v1/payment-methods/{uuid}/set-default → Try in Playground

Marks one payment method as the default for its customer — scoped per customer + brand + gateway, since a payment method for one gateway can never recharge a subscription on another.

Path parameters

Returns 200 OK.

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 · subscription.created · subscription.paused · subscription.resumed · subscription.plan_changed · subscription.payment_method_updated · subscription.trial_ending · subscription.upcoming_charge — charged/failed fire from POST /v1/payments/charge and the automatic renewal cycle; the rest fire from the Subscriptions management endpoints and the compliance notice scheduler.

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.