REST API для приёма Kaspi Pay.

curl -X POST https://pay.arzan.cloud/api/v1/payment-links \
  -H "X-API-Key: $ARZAN_KEY" \
  -H "Idempotency-Key: cart_a-2041" \
  -d '{
    "amount": 24500,
    "comment": "Корзина A-2041",
    "external_order_id": "cart_a-2041"
  }'

# Ответ:
# {
#   "id": "inv_...",
#   "payment_url": "https://pay.kaspi.kz/pay/XXXX",
#   "deeplink":    "https://pay.kaspi.kz/pay/XXXX",
#   "qr_token":    "https://pay.kaspi.kz/pay/XXXX",
#   "amount": "24500.00",
#   "status": "pending"
# }

const link = await fetch('https://pay.arzan.cloud/api/v1/payment-links', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ARZAN_KEY,
    'Idempotency-Key': `cart_${cartId}`,
  },
  body: JSON.stringify({
    amount: cart.total,
    comment: `Корзина ${cartId}`,
    external_order_id: `cart_${cartId}`,
  }),
}).then((r) => r.json());

// link.payment_url — открывается в браузере
// link.deeplink — открывает Kaspi сразу на мобильном
return { qr_url: link.payment_url, open_in_kaspi: link.deeplink };

# Полный возврат
curl -X POST https://pay.arzan.cloud/api/v1/invoices/inv_e80bbb3b/refund \
  -H "X-API-Key: $ARZAN_KEY"

# Частичный возврат
curl -X POST https://pay.arzan.cloud/api/v1/refunds \
  -H "X-API-Key: $ARZAN_KEY" \
  -d '{
    "invoice_id": "inv_e80bbb3b",
    "amount": 2000,
    "reason": "Возврат части товара"
  }'

// Полный возврат
await fetch(`https://pay.arzan.cloud/api/v1/invoices/${invoiceId}/refund`, {
  method: 'POST',
  headers: { 'X-API-Key': process.env.ARZAN_KEY },
});

// Частичный возврат
await fetch('https://pay.arzan.cloud/api/v1/refunds', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.ARZAN_KEY },
  body: JSON.stringify({
    invoice_id: invoiceId,
    amount: 2000,
    reason: 'Возврат части товара',
  }),
});

import crypto from 'node:crypto';
import express from 'express';

const app = express();
// ВАЖНО: raw body, не используйте express.json() ДО проверки
app.use('/webhook', express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
  const sig = req.headers['x-webhook-signature'];
  const ts = Number(req.headers['x-webhook-timestamp']);

  // 1. Anti-replay: timestamp не старше 5 мин
  if (!ts || Math.abs(Math.floor(Date.now() / 1000) - ts) > 5 * 60) {
    return res.status(401).send('stale or missing timestamp');
  }

  // 2. Подпись над `.`
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${ts}.${req.body}`)
    .digest('hex');

  if (!sig || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('bad signature');
  }

  const event = JSON.parse(req.body.toString('utf8'));
  // обработать event
  res.status(200).send('ok');
});

import hmac, hashlib, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ['WEBHOOK_SECRET']

@app.post('/webhook')
def webhook():
    raw = request.get_data()  # raw body
    sig = request.headers.get('X-Webhook-Signature', '')
    ts = request.headers.get('X-Webhook-Timestamp', '')

    # 1. Anti-replay: timestamp не старше 5 мин
    try:
        ts_int = int(ts)
    except ValueError:
        abort(401, 'bad timestamp')
    if abs(int(time.time()) - ts_int) > 5 * 60:
        abort(401, 'stale timestamp')

    # 2. Подпись над `.`
    expected = 'sha256=' + hmac.new(
        SECRET.encode(),
        f"{ts_int}.".encode() + raw,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(sig, expected):
        abort(401, 'bad signature')

    event = request.get_json()
    return 'ok', 200

<?php
$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$ts  = (int)($_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? 0);
$secret = getenv('WEBHOOK_SECRET');

// 1. Anti-replay
if (!$ts || abs(time() - $ts) > 5 * 60) {
    http_response_code(401);
    exit('stale timestamp');
}

// 2. Подпись над `.`
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);

if (!hash_equals($expected, $sig)) {
    http_response_code(401);
    exit('bad signature');
}

$event = json_decode($raw, true);
http_response_code(200);
echo 'ok';

curl https://pay.arzan.cloud/api/v1/invoices/inv_e80bbb3b \
  -H "X-API-Key: $ARZAN_KEY"

curl -X POST https://pay.arzan.cloud/api/v1/invoices/status/check \
  -H "X-API-Key: $ARZAN_KEY" \
  -d '{ "invoice_ids": ["inv_a", "inv_b", "inv_c"] }'