ApiPay.kz API — For AI Agents

Quick Reference

Pricing — NO Hidden Fees

Important: ApiPay.kz does NOT charge any percentage from your sales. All plans include ALL features. No blocking on exceeding transaction limits — our manager will contact you proactively.

Two Ways to Use ApiPay.kz

1. Dashboard UI (No Code Required)

• Create invoices manually via web interface
• View payment history and statuses
• Configure webhooks through Settings
• Manage recurring invoices
• Process refunds with one click

Best for: Small businesses, manual invoice creation, testing

2. REST API (For Developers)

• Automate invoice creation from your website/app
• Integrate into checkout flow
• Build custom payment solutions
• Receive webhook notifications programmatically

Best for: E-commerce, SaaS, automated billing

Both options include ALL features: invoices, recurring payments, refunds, webhooks.

Documentation Resources

API Endpoints

Invoices

Catalog

Subscriptions

Refunds

Note: Webhooks are configured in the ApiPay.kz dashboard, not via API.

Invoice Statuses

Error Codes

Code Examples

Create Invoice (JavaScript)

const response = await fetch('https://bpapi.bazarbay.site/api/v1/invoices', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 15000,
    phone_number: '87001234567',
    description: 'Order #123',
    external_order_id: 'order_123'
  })
});
const { id, amount, status, created_at } = await response.json();
// Customer receives notification in Kaspi app

Create Invoice (Python)

import requests

response = requests.post(
    'https://bpapi.bazarbay.site/api/v1/invoices',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={
        'amount': 15000,
        'phone_number': '87001234567',
        'description': 'Order #123'
    }
)
data = response.json()
# Customer receives notification in Kaspi app
print(f"Invoice created: {data['id']}")

Create Invoice (cURL)

curl -X POST https://bpapi.bazarbay.site/api/v1/invoices \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 15000, "phone_number": "87001234567"}'

Subscription — Automatic Billing (JavaScript)

// Create subscription for automatic billing
const response = await fetch('https://bpapi.bazarbay.site/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 5000,
    phone_number: '87001234567',
    description: 'Monthly subscription',
    billing_period: 'monthly',  // daily, weekly, biweekly, monthly, quarterly, yearly
    billing_day: 15             // optional: day of period (1-28)
  })
});
const { subscription } = await response.json();

// Manage subscription:
// POST /subscriptions/:id/pause   - pause billing
// POST /subscriptions/:id/resume  - resume after pause
// POST /subscriptions/:id/cancel  - cancel permanently

Full Refund (JavaScript)

// Full refund for paid invoice
await fetch('https://bpapi.bazarbay.site/api/v1/invoices/42/refund', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
// Returns: { id, invoice_id, amount, status: 'completed' }

Partial Refund (JavaScript)

// Partial refund - specify amount and optional reason
await fetch('https://bpapi.bazarbay.site/api/v1/invoices/42/refund', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 5000,              // partial amount to refund
    reason: 'Partial return'   // optional reason
  })
});

// Get all refunds: GET /refunds
// Get refunds for invoice: GET /invoices/:id/refunds

Subscription (Python)

import requests

# Create subscription
response = requests.post(
    'https://bpapi.bazarbay.site/api/v1/subscriptions',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={
        'amount': 5000,
        'phone_number': '87001234567',
        'description': 'Monthly subscription',
        'billing_period': 'monthly'
    }
)
subscription = response.json()['subscription']

# Pause subscription
requests.post(
    f'https://bpapi.bazarbay.site/api/v1/subscriptions/{subscription["id"]}/pause',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)

Refund (Python)

import requests

# Full refund
requests.post(
    'https://bpapi.bazarbay.site/api/v1/invoices/42/refund',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)

# Partial refund
requests.post(
    'https://bpapi.bazarbay.site/api/v1/invoices/42/refund',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={'amount': 5000, 'reason': 'Partial return'}
)

Webhook Verification (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Integration Steps

1. Register at apipay.kz/login
2. Contact support via WhatsApp (+7 708 516 74 89) to connect your Kaspi Business as "Cashier"
3. Wait for organization to be connected (usually 5-30 minutes)
4. Create invoices via POST /invoices
5. Configure webhook in dashboard (Settings → Connection)

Request/Response Examples

POST /invoices Request

{
  "amount": 15000,              // Required: 0.01 - 99999999.99
  "phone_number": "87001234567", // Required: 8XXXXXXXXXX format
  "description": "Order #123",   // Optional: max 500 chars
  "external_order_id": "order_123" // Optional: your order ID
}

POST /invoices Response (201 Created)

{
  "id": 42,
  "amount": "15000.00",
  "status": "pending",
  "created_at": "2025-01-22T10:30:00Z"
}

GET /invoices/:id Response

{
  "id": 42,
  "amount": "15000.00",
  "total_refunded": "0.00",
  "is_fully_refunded": false,
  "description": "Order #123",
  "status": "pending",
  "paid_at": null,
  "is_sandbox": false,
  "is_recurring": false,
  "kaspi_invoice_id": "13234689513",
  "client_name": null,
  "client_comment": null,
  "created_at": "2025-01-22T10:30:00.000000Z"
}

Webhook Event

{
  "event": "invoice.status_changed",
  "invoice": {
    "id": 42,
    "external_order_id": "order_123",
    "amount": "15000.00",
    "status": "paid",
    "client_name": "John Doe",
    "client_phone": "87071234567",
    "paid_at": "2025-01-22T14:35:00Z"
  },
  "timestamp": "2025-01-22T14:35:01Z"
}