HızlıKasa API Reference.

Seamlessly integrate secure payments into your platform. Accept credit cards via Stripe/Ziina and USDT TRC20 crypto payments with a unified, developer-friendly API.

Base URL:https://hizlikasa.co/api

RESTful

Standard JSON responses

Secure

TLS 1.3 + HMAC Signatures

Real-time

< 200ms Latency

Authentication

Authenticate your requests by including your secret API key in the x-api-key header. Keep this key secure and never expose it in client-side code.

HEADERS

x-api-key: sk_live_51M...

Create Payment

Initialize a payment session. This endpoint creates a transaction and returns a payment URL for cards or wallet details for crypto.

POST/api/payment/create

Parameters

amountnumberREQUIRED
Transaction amount (e.g. 500.00)
currencystring
Default: TRY
fullNamestringREQUIRED
Customer name
emailstringREQUIRED
Customer email
phonestringREQUIRED
Customer phone (+90...)
externalRefstringREQUIRED
Your unique order ID
callbackUrlstring
Webhook for updates
returnUrlstring
Redirect after payment
cancelUrlstring
Redirect if payment is cancelled
invoiceSitestring
INTERNAL: Forces facade mode (vault/theme/clickad)
metadataobject
Custom data { siteId: ... }
providerstring
Optional: "crypto" or "card"

Example Request

cURL

curl -X POST https://hizlikasa.co/api/payment/create \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000.00,
    "fullName": "Ahmet Yilmaz",
    "email": "[email protected]",
    "phone": "+905551234567",
    "externalRef": "ORD-2024-001",
    "callbackUrl": "https://api.site.com/webhook",
    "metadata": {
       "userId": "123456"
    },
    "invoiceSite": "vault",
    "returnUrl": "https://vault.visiontech.co/success",
    "cancelUrl": "https://vault.visiontech.co/cancel"
    }
  }'

Response (Card)

JSON

{
  "success": true,
  "transactionId": "txn_abc123",
  "provider": "stripe",
  "redirectUrl": "https://checkout.stripe.com/..."
}

Crypto Payments

Set provider: "crypto" in your creation request. We currently support USDT TRC20 (Tron Network).

Min: 100 TL

Max: 500,000 TL

Unlimited Daily

Crypto Request

JSON

{
  "amount": 10000.00,
  "provider": "crypto",
  "currency": "TRY",
  "fullName": "Ahmet Yilmaz",
  "externalRef": "ORD-2024"
}

Response Object

JSON

{
  "success": true,
  "provider": "crypto",
  "data": {
    "walletAddress": "TXj9...",
    "amount": 281.69,
    "currency": "USDT",
    "network": "TRC20"
  }
}

Flow: Display QR code with wallet address → User sends USDT → Our system auto-detects transaction → Callback sent to your URL.

Scan Frequency

Every 60s

Tolerance

±0.01 USDT

Timeout

60 min

Note: Exchange rate is fetched live from Binance API. Amount in USDT is calculated at time of payment creation.

Important: Crypto payments do not generate invoices or send emails. Only the callback webhook is triggered.

Supported Networks

TRC20 (TRON)ERC20 (Coming Soon)BEP20 (Coming Soon)

Bridge & Facade Mode

The Ghost Bridge protocol allows you to process payments through HızlıKasa while presenting a different Facade (Identity) to the Payment Provider (prop, Ziina, Telr). This ensures complete risk isolation and referrer masking.

How to Trigger Ghost Mode

Simply send the invoiceSite parameter in your create request.

Vault FacadeinvoiceSite: "vault"

Applies "Cloud Services" cover product.

Theme FacadeinvoiceSite: "theme"

Applies "Digital Theme" cover product.

Check Status

GET/api/payment/status?ref=ORDER_123

pending

processing

completed

failed

expired

refunded

Response

JSON

{
  "success": true,
  "transaction": {
    "id": "txn_abc123",
    "externalRef": "ORDER_123",
    "amount": 1000.00,
    "status": "completed"
  }
}

Webhooks

We send POST requests to your callbackUrl when status changes.

Headers

Header	Description
X-Signature	HMAC-SHA256 signature
X-Timestamp	ISO timestamp
X-Attempt	Retry attempt (1-5)

Payload

JSON

{
  "event": "payment.completed",
  "transactionId": "txn_839210",
  "externalRef": "ORDER_123",
  "status": "completed",
  "amount": 1000.00,
  "currency": "TRY",
  "fullName": "Ahmet Yilmaz",
  "timestamp": "2025-01-15...",
  "signature": "hmac_sha256...",
  "metadata": {...}
}

Signature Format

Data String

{transactionId}:{externalRef}:{status}:{amount}:{timestamp}

Verification (Node.js)

Node.js

const dataString = `${txId}:${ref}:${status}:${amount}:${ts}`;
const expected = crypto
  .createHmac('sha256', secret)
  .update(dataString).digest('hex');
// Use timingSafeEqual for comparison

Retry Policy

1m5m15m1h4h

Requirement: Your endpoint MUST return HTTP 200 with {received: true} to acknowledge receipt. Otherwise we will retry.

Webhook Source IP

All webhooks originate from these IPs. You may whitelist them in your firewall:

135.181.236.205Primary (Hetzner EU)

Digitain Integration

This section covers the specific requirements for integrating HızlıKasa with Digitain gaming platform.

Required Fields

Field	Required	Description
amount	✓	Deposit amount in TRY
fullName	✓	Player full name from Digitain
email	✓	Player email
phone	✓	Player phone (+90...)
externalRef	✓	Digitain Transaction ID (unique)
callbackUrl	✓	Webhook endpoint for payment updates
returnUrl	✓	URL to redirect player after payment
metadata.userId	✓	Digitain Player/Member ID
metadata.siteId	—	Site identifier (fenomenbet.com)

callbackUrl

Server-to-Server: Webhook notification when payment status changes. Must return HTTP 200.

returnUrl

Browser Redirect: Player is redirected here after clicking "Return to Site" button on success page.

Example Request

JSON

{
  "amount": 5000.00,
  "currency": "TRY",
  "fullName": "Ahmet Yilmaz",
  "email": "[email protected]",
  "phone": "+905551234567",
  "externalRef": "DGT-TXN-487538323",
  "callbackUrl": "https://api.digitain.com/...",
  "returnUrl": "https://fenomenbet.com/...",
  "metadata": {
    "userId": "11420076",
    "siteId": "fenomenbet.com"
  }
}

User Limit Tracking

Limits are tracked by multiple identifiers to prevent abuse. The strictest limit applies.

Daily

10 txn

Weekly

35 txn

Monthly

100 txn

Tracked by: email, phone, externalRef (member ID)

Payment Flow

Digitain → HızlıKasa: POST /api/payment/create with player data

Response: Receive redirectUrl and transactionId

Redirect player to redirectUrl for payment

Player completes payment → Sees success page → Clicks "Return to Site"

Browser redirect to returnUrl (back to betting site)

⚡

Webhook (async): POST to callbackUrl with payment status

Error Codes

Code	HTTP	Description
INVALID_REQUEST	400	Malformed request body
INVALID_AMOUNT	400	Amount out of range (Card: 500-50000, Crypto: 100-500000 TRY)
INVALID_EMAIL	400	Invalid email format
INVALID_PHONE	400	Invalid phone format
DUPLICATE_REF	409	externalRef already exists
UNAUTHORIZED	401	Invalid or missing API key
RATE_LIMITED	429	Too many requests - check Retry-After header
PROVIDER_ERROR	502	Payment provider error (Stripe/Ziina/Crypto)
SYSTEM_DISABLED	503	Payment system temporarily disabled
SERVER_ERROR	500	Internal server error

Testing

Use these test cards to simulate scenarios in sandbox mode.

Test Cards

4242 4242 4242 4242SUCCESS

4000 0000 0000 0002DECLINED

4000 0000 0000 9995INSUFFICIENT FUNDS

4000 0025 0000 31553D SECURE

Use any future expiry date and any 3-digit CVC.

Idempotency

externalRef acts as your idempotency key. Protects against duplicate payments from retries or double-clicks.

Scenario	Behavior
Same ref, same amount	Returns existing transaction
Same ref, different amount	Error: DUPLICATE_REF

Session Timeouts

Card Payments

30 minutes

Crypto Payments

60 minutes

Getting Started

Contact [email protected] for API credentials
Receive API Key + Webhook Secret
Configure your callback URL

Rate Limits

Create Payment

5 req/min

per IP

Status Check

30 req/min

per IP

Webhooks

100 req/min

outgoing

429 Response: If rate limited, check Retry-After header for seconds until next request allowed.

Need Higher Limits?

[email protected]

SDK Examples

Python

class HizliKasaClient:
  def __init__(self, api_key, secret):
    self.api_key = api_key
    self.secret = secret
    self.base = "https://hizlikasa.co/api"

  def create_payment(self, amount, ...):
    return requests.post(
      f"{self.base}/payment/create",
      headers={"x-api-key": self.api_key},
      json={...}
    ).json()

  def verify_webhook(self, payload, sig):
    data = f"{txId}:{ref}:{status}:..."
    expected = hmac.new(...).hexdigest()
    return hmac.compare_digest(sig, expected)

Currency Support

Currency	Card	Crypto
TRY (Turkish Lira)	✓	✓ → USDT
USDT (TRC20)	—	✓

All amounts are specified in TRY. For crypto, TRY is converted to USDT at live exchange rate locked at payment creation.