# Quickpay.ge API

> Georgian payment gateway aggregator. Integrate once to accept payments via BOG, TBC, Credo, and 15+ other Georgian gateways.

Base URL: https://api.quickpay.ge/v1
Auth: Bearer token (Authorization: Bearer qpk_live_...)
Docs: https://quickpay.ge/docs
Full docs (Markdown): https://quickpay.ge/api-docs.md
OpenAPI spec: https://quickpay.ge/docs/api

## Payment Flows

- **Card payment** — One-time card charge. Customer enters card details at the bank's secure interface. Visa/MC, Apple Pay, and Google Pay where supported. Slugs: bog_card · tbc_card · flitt · unipay · fastoo · moka · keepz
- **Installment loan** — Customer picks a repayment plan (3–36 months). Merchant receives the full amount upfront — the bank handles instalment collection. Slugs: bog_installment · tbc_installment · credo_installment · flitt_installment
- **BNPL (0% financing)** — Buy-now-pay-later split into equal 0-interest instalments. The bank absorbs the financing cost — no extra charge to customer or merchant. Slugs: bog_bnpl · flitt_bnpl
- **Open banking / QR / Wallet** — Card + QR code + open banking + digital wallet in one gateway. Supports all major Georgian banks via open banking. Slugs: keepz · paysera
- **Crypto** — Customer pays in cryptocurrency. CityPay handles the conversion and settles GEL to the merchant. No crypto wallet required on the merchant side. Slugs: citypay
- **Offline / manual** — No hosted payment page. Bank transfer: customer receives your IBAN + order UUID as reference. COD: merchant confirms delivery manually. Slugs: bank_transfer · cash_on_delivery

For all flows: POST /v1/payments → redirect to payment_url → receive payment.paid webhook. The gateway_slug field determines the flow.

## Official SDKs

- **PHP SDK** (`quickpay/php-sdk`, `composer require quickpay/php-sdk`) — https://quickpay.ge/php-sdk · https://github.com/QuickPayGe/php-sdk
- **Laravel Package** (`quickpay/laravel`, `composer require quickpay/laravel`) — https://quickpay.ge/laravel-package · https://github.com/QuickPayGe/laravel-package
- **Node.js / TypeScript SDK** (`@quickpay/js`, `npm install @quickpay/js`) — https://quickpay.ge/node-sdk · https://github.com/QuickPayGe/node-sdk

## Platform Plugins

Native plugins for e-commerce and billing platforms — configured with an API key, no code required.
- WooCommerce (WordPress) — https://quickpay.ge/wordpress-plugin
- WHMCS — https://quickpay.ge/whmcs-plugin
- OpenCart — https://quickpay.ge/opencart-plugin
- CS-Cart — https://quickpay.ge/cscart-plugin
- PrestaShop — https://quickpay.ge/prestashop-plugin
- Easy Digital Downloads (WordPress) — https://quickpay.ge/edd-plugin

## Endpoints

- POST  /v1/payments — 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.
- GET   /v1/payments/{uuid} — Returns the full payment object.
- GET   /v1/payments — Returns a paginated list (20 per page) sorted newest first.
- POST  /v1/payments/{uuid}/refund — Initiates a full or partial refund. Omit amount to refund the full remaining amount. Returns the updated payment object.
- GET   /v1/products — Returns a paginated list (20 per page) sorted newest first.
- POST  /v1/products — At least one of name_en or name_ka is required.
- GET   /v1/products/{uuid} — Returns the full product object.
- PUT   /v1/products/{uuid} — Partial update — include only the fields you want to change. Same field rules as create. Returns the full product object.
- DELETE/v1/products/{uuid} — Deletes the product.
- POST  /v1/checkout-links — Creates a reusable payment link. Provide either product_uuid (price comes from the product) or a fixed amount.
- GET   /v1/invoices — Returns a paginated list (20 per page) sorted newest first.
- POST  /v1/invoices — 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.
- GET   /v1/invoices/{uuid} — Returns the full invoice object including payment_url, sent_at, viewed_at, and paid_at timestamps.
- POST  /v1/invoices/{uuid}/send — Emails the invoice to the customer and transitions status to sent. Cannot be called when status is paid or cancelled.
- GET   /v1/gateways — 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.
- GET   /v1/checkout-templates — 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.
- GET   /v1/exchange-rates — Public endpoint — no authentication required. Converts an amount between two currencies using live rates.
- POST  /v1/payments/charge — Charge a stored subscription token (recurring)

## Webhooks

Quickpay POSTs to your webhook URL on status changes.
Payment events: payment.paid · payment.failed · payment.refunded · payment.partially_refunded · payment.refund_pending · payment.cancelled · payment.expired
Subscription events: subscription.charged · subscription.failed
Invoice events: invoice.paid
Lead events: lead.submitted
Signature header: QUICKPAY-SIGNATURE: t={timestamp},v1={hmac_sha256(webhook_secret, "{timestamp}.{json_payload}")}
Max 5-minute timestamp skew. Your endpoint must return HTTP 2xx within 30 seconds; failed deliveries are retried up to 5 times.

## Key concepts

- All amounts are decimal numbers (e.g. 149.99). Default currency: GEL. Supported: GEL, USD, EUR, GBP.
- Idempotency-Key header on POST requests prevents double-charges (200 on replay; 409 on amount/currency mismatch).
- API keys are brand-scoped: qpk_live_... (production) / qpk_test_... (sandbox).
- gateway_slug is optional on payment creation — omit to show all gateways to the customer.
- Test keys only work when the brand is in test mode — no real gateway calls are made.
- Rate limit: 100 req/min per API key (X-RateLimit-Limit / X-RateLimit-Remaining headers).

## Recurring Payments

Available subscription slugs: bog_card_subscriptions, tbc_card_subscriptions, flitt_subscriptions, unipay_subscriptions, fastoo_subscriptions, paypal_subscriptions, liberty_card_subscriptions
1. Initial charge: POST /v1/payments with a _subscriptions slug → customer pays on hosted page → payment.paid webhook includes a subscription_token (UUID) — save it.
2. Subsequent charges: POST /v1/payments/charge { subscription_token, amount } → 202 → subscription.charged webhook on success (subscription.failed on failure). Amount can be overridden per call. Minimum 24h between charges (429 charge_too_frequent with retry_after if violated).

## Error Codes

| error_code | HTTP | When it occurs |
|---|---|---|
| missing_api_key | 401 | No Authorization header |
| invalid_api_key | 401 | Key does not exist or was revoked |
| account_suspended | 403 | Merchant account is suspended |
| test_key_live_mode | 403 | Test key used on a live-mode brand |
| live_key_test_mode | 403 | Live key used on a test-mode brand |
| no_gateway_license | 403 | No active module subscription for this gateway |
| idempotency_conflict | 409 | Same Idempotency-Key with a different amount or currency |
| not_found | 404 | Resource does not exist |
| validation_failed | 422 | Request payload failed validation |
| rate_limit_exceeded | 429 | More than 100 req/min per key |
| gateway_unavailable | 500 | Gateway API is temporarily down |
| coupon_not_found | 422 | Coupon code does not exist |
| coupon_inactive | 422 | Coupon is disabled |
| coupon_not_started | 422 | Coupon start date has not arrived |
| coupon_expired | 422 | Coupon has expired |
| coupon_product_mismatch | 422 | Coupon is only valid for a different product |
| coupon_below_min_amount | 422 | Order amount is below the coupon minimum |
| coupon_max_uses_reached | 422 | Coupon has been fully redeemed |
| coupon_per_customer_limit | 422 | Customer has already used this coupon |
| coupon_code_taken | 422 | A coupon with this code already exists for the brand |
| line_items_mismatch | 422 | Sum of line_items totals ≠ amount |
| template_not_found | 422 | checkout_template_id does not exist |
| select_options_required | 422 | select/radio field missing its options array |
| amount_or_product_required | 422 | Neither amount nor product_uuid was provided |
| refund_exceeds_remaining | 422 | Refund amount > remaining refundable amount |
| payment_not_refundable | 422 | Payment status does not allow refunds |
| payment_not_cancellable | 422 | Payment status does not allow cancellation |
| gateway_refund_unsupported | 422 | This gateway does not support API refunds |
| invoice_not_sendable | 422 | Invoice is paid or cancelled |
| subscription_not_found | 404 | subscription_token does not exist or belongs to a different brand |
| subscription_inactive | 422 | Subscription is cancelled or has expired |
| subscription_already_cancelled | 422 | Subscription is already cancelled |
| charge_too_frequent | 429 | A charge was already initiated within the last 24 hours |
| webhook_not_configured | 422 | No webhook URL is configured for the brand |