BOTONPAY Public API

# 1) проверка доступности API
curl -s https://botonpay.org/api/public/v1/health

# 2) создание сделки на 5000 RUB
curl -X POST https://botonpay.org/api/public/v1/deals \
  -H "Authorization: Bearer bp_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8b3f4c02-3f6f-4c88-9e02-0b3e9b3e0e7a" \
  -d '{
    "merchant_order_id": "019fd47b-3e40-746f-b7dd-96aaf5971190",
    "fiat": "RUB",
    "amount_fiat": 5000,
    "callback_url": "https://merchant.example.com/webhooks/botonpay"
  }'

# ответ: HTTP 201 Created

Локальный заказ (merchant_order_id + Idempotency-Key)
  → POST /api/public/v1/deals
  → HTTP 201 Created   (deal_uuid, реквизиты, payment_url, expires_at)
  → webhook deal.created    / status = waiting_payment
  → webhook deal.processing / status = processing
  → webhook deal.completed  / status = completed        ← финальный успех

Отмена:
  → HTTP 201 → deal.created / waiting_payment → deal.cancelled / cancelled

Истечение:
  → HTTP 201 → deal.created / waiting_payment → deal.expired / expired

Base URL: https://botonpay.org/api/public/v1

{
  "success": false,
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency-Key was already used with different request parameters"
  }
}

POST https://botonpay.org/api/public/v1/deals
Authorization: Bearer bp_live_...
Idempotency-Key: 8b3f4c02-3f6f-4c88-9e02-0b3e9b3e0e7a
Content-Type: application/json

{ "merchant_order_id": "ORDER-124", "fiat": "RUB", "amount_fiat": 5000 }

POST https://botonpay.org/api/public/v1/deals
Authorization: Bearer bp_live_...
Idempotency-Key: 2f3c1a55-6b21-4c6e-9d1f-2b18cf0a71cd
Content-Type: application/json

{ "merchant_order_id": "ORDER-125", "fiat": "TRY", "amount_fiat": 2500, "client_name": "Ahmet Yilmaz" }

// 400 если client_name не передан:
{ "success": false, "error": { "code": "invalid_request",
  "message": "client_name is required for TRY deals" } }

GET https://botonpay.org/api/public/v1/deals/by-idempotency-key/8b3f4c02-3f6f-4c88-9e02-0b3e9b3e0e7a
Authorization: Bearer bp_live_...

// 200 — исходный ответ Create Deal (Idempotent-Replayed: true)
// 202 — запрос ещё обрабатывается:
{ "success": false, "processing": true,
  "error": { "code": "DEAL_CREATION_PROCESSING",
             "message": "Deal creation is still processing. Retry shortly." } }

POST https://botonpay.org/api/public/v1/deals
Authorization: Bearer bp_live_...
Idempotency-Key: 8b3f4c02-3f6f-4c88-9e02-0b3e9b3e0e7a
Content-Type: application/json

{
  "merchant_order_id": "ORDER-124",
  "fiat": "RUB",
  "amount_fiat": 5000,
  "callback_url": "https://merchant.com/webhook",
  "success_url": "https://merchant.com/success",
  "cancel_url": "https://merchant.com/cancel",
  "customer_id": "USER-123"
}

{
  "success": true,
  "deal": {
    "id": "b3a1c9e0-1234-4abc-9def-1234567890ab",
    "deal_uuid": "b3a1c9e0-1234-4abc-9def-1234567890ab",
    "external_id": "D-1042",
    "status": "waiting_payment",
    "merchant_order_id": "ORDER-124",
    "fiat": "RUB",
    "amount_fiat": 5000,
    "amount_usdt": 62.81,
    "rate": 79.60,
    "exchange_rate": "79.60000000",
    "exchange_rate_direction": "fiat_to_usdt",
    "gross_amount_usdt": "62.81407035",
    "merchant_fee_percent": "5.0000",
    "merchant_fee_usdt": "3.14070352",
    "merchant_net_amount_usdt": "59.67336683",
    "merchant_amount_usdt": "59.67336683",
    "calculation_status": "locked",
    "created_at": "2026-01-01T00:00:00Z",
    "expires_at": "2026-01-01T00:10:00Z",
    "payment_url": "https://botonpay.org/pay/d/abc123xyz",
    "deal_url": "https://botonpay.org/pay/d/abc123xyz",
    "requisites_id": "9f1e2b45-aaaa-bbbb-cccc-1234567890ab",
    "payment_details": {
      "bank": "T-Bank",
      "holder": "Ivan Ivanov",
      "card": "2200123412341234"
    }
  }
}

POST https://botonpay.org/api/public/v1/deals
Authorization: Bearer bp_live_...
Idempotency-Key: 8b3f4c02-3f6f-4c88-9e02-0b3e9b3e0e7a
Content-Type: application/json

{
  "merchant_order_id": "ORDER-125",
  "currency": "KZT",
  "amount_fiat": 50000,
  "payment_method": "card",
  "bank_code": "halyk",
  "callback_url": "https://merchant.com/webhook"
}

{
  "merchant_order_id": "ORDER-126",
  "currency": "KZT",
  "amount_fiat": 50000,
  "payment_method": "phone",
  "bank_code": "kaspi",
  "callback_url": "https://merchant.com/webhook"
}

{
  "success": true,
  "deal": {
    "payment_method": "phone",
    "requested_payment_method": "phone",
    "requisites": {
      "bank_name": "Kaspi Bank",
      "recipient_name": "АЙДОС К.",
      "payment_method": "phone",
      "card_number": null,
      "phone": "+7 700 123 45 67"
    }
  }
}

GET https://botonpay.org/api/public/v1/deals/b3a1c9e0-1234-4abc-9def-1234567890ab
Authorization: Bearer bp_live_...

{
  "success": true,
  "deal": {
    "id": "b3a1c9e0-1234-4abc-9def-1234567890ab",
    "deal_uuid": "b3a1c9e0-1234-4abc-9def-1234567890ab",
    "external_id": "D-1042",
    "status": "completed",
    "merchant_order_id": "ORDER-124",
    "fiat": "RUB",
    "amount_fiat": 5000,
    "amount_usdt": 62.81,
    "gross_amount_usdt": "62.81407035",
    "merchant_fee_percent": "5.0000",
    "merchant_fee_usdt": "3.14070352",
    "merchant_amount_usdt": "59.67336683",
    "calculation_status": "locked",
    "created_at": "...",
    "completed_at": "..."
  }
}

GET https://botonpay.org/api/public/v1/deals/by-merchant-order/ORDER-124
Authorization: Bearer bp_live_...

GET https://botonpay.org/api/public/v1/deals?status=completed&page=1&limit=20
Authorization: Bearer bp_live_...

{
  "success": true,
  "data": [ /* Deal[] */ ],
  "page": 1,
  "limit": 20,
  "total": 137,
  "pages": 7,
  "has_next": true,
  "has_prev": false
}

POST https://botonpay.org/api/public/v1/deals/b3a1c9e0-1234-4abc-9def-1234567890ab/cancel
Authorization: Bearer bp_live_...

{ "success": true, "status": "cancelled" }

POST https://botonpay.org/api/public/v1/deals/ORDER-124/appeal
Authorization: Bearer bp_live_...
Content-Type: application/json

{
  "reason": "Клиент оплатил 1500 TRY, чек приложен, но сделка отменена",
  "files": [
    { "name": "receipt.pdf", "type": "application/pdf", "data": "JVBERi0xLjQK..." }
  ]
}

{
  "success": true,
  "deal_id": "b3a1c9e0-1234-4abc-9def-1234567890ab",
  "appeal": {
    "appeal_id": "7aae91ea-f656-4cf9-9e95-8c20ac6bf4f2",
    "status": "open",
    "reason": "Клиент оплатил 1500 TRY, чек приложен, но сделка отменена",
    "rejection_reason": null,
    "resolution_note": null,
    "evidence_count": 1,
    "created_at": "2026-08-11T09:12:21.510Z",
    "resolved_at": null,
    "deal_status": "disputed"
  }
}

GET https://botonpay.org/api/public/v1/deals/ORDER-124/appeal
Authorization: Bearer bp_live_...

{
  "event": "deal.appeal_resolved",
  "deal_id": "b3a1c9e0-1234-4abc-9def-1234567890ab",
  "merchant_order_id": "ORDER-124",
  "status": "completed",
  "fiat": "TRY",
  "amount_fiat": 1500.00,
  "amount_usdt": 30.36437247,
  "rate": 49.4,
  "appeal": {
    "appeal_id": "7aae91ea-f656-4cf9-9e95-8c20ac6bf4f2",
    "status": "resolved_client",
    "outcome": "merchant",
    "reason": "Клиент оплатил 1500 TRY, чек приложен, но сделка отменена",
    "rejection_reason": null,
    "resolution_note": "Платёж найден в выписке",
    "created_at": "2026-08-11T09:12:21.510Z",
    "resolved_at": "2026-08-11T10:04:03.117Z"
  },
  "timestamp": "2026-08-11T10:04:03.200Z"
}

{
  "event": "deal.appeal_resolved",
  "deal_id": "b3a1c9e0-1234-4abc-9def-1234567890ab",
  "status": "cancelled",
  "cancellation_reason": "dispute_resolved",
  "appeal": {
    "appeal_id": "7aae91ea-f656-4cf9-9e95-8c20ac6bf4f2",
    "status": "resolved_trader",
    "outcome": "provider",
    "rejection_reason": "payment_not_received",
    "resolution_note": "Платёж на реквизит не поступал",
    "resolved_at": "2026-08-11T10:04:03.117Z"
  }
}

GET https://botonpay.org/api/public/v1/health

{
  "status": "ok",
  "version": "1.3.0",
  "database": "ok",
  "webhooks": "ok",
  "exchange_rate": "ok",
  "webhook_worker": "ok",
  "telegram_webhook": "configured",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

POST https://merchant.com/webhook
X-Signature: <hmac_sha256_hex>
X-Webhook-Event: deal.created
X-Webhook-Id: 6f0a5e1b-8f2a-4b6d-8f2e-95a1d7c0f3a2
X-Webhook-Attempt: 1
Content-Type: application/json

{
  "event": "deal.created",
  "deal_uuid": "b3a1c9e0-1234-4abc-9def-1234567890ab",
  "deal_id": "b3a1c9e0-1234-4abc-9def-1234567890ab",
  "merchant_order_id": "ORDER-124",
  "previous_status": null,
  "status": "waiting_payment",
  "status_version": 1,
  "fiat": "RUB",
  "amount_fiat": 5000,
  "amount_usdt": 62.81,
  "rate": 79.60,
  "client_name": null,
  "expected_sender_name": null,
  "environment": "live",
  "is_test": false,
  "metadata": { "product_id": "sku_42" },
  "event_created_at": "2026-01-01T00:00:00.000Z",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

{
  "event": "deal.cancelled",
  "deal_uuid": "8f1c2f6e-1d5a-4a1b-9f30-3a2f9b7c1e44",
  "deal_id": "8f1c2f6e-1d5a-4a1b-9f30-3a2f9b7c1e44",
  "merchant_order_id": "ORDER-1042",
  "previous_status": "waiting_payment",
  "status": "cancelled",
  "status_version": 2,
  "cancellation_reason": "merchant_cancelled",
  "cancelled_at": "2026-08-06T00:00:00.000Z",
  "event_created_at": "2026-08-06T00:00:00.500Z",
  "timestamp": "2026-08-06T00:00:00.500Z"
}

POST https://merchant.com/webhook
X-Signature: <hmac_sha256_hex>
X-Webhook-Event: deal.completed
Content-Type: application/json

{
  "event": "deal.completed",
  "deal_uuid": "b3a1c9e0-1234-4abc-9def-1234567890ab",
  "deal_id": "b3a1c9e0-1234-4abc-9def-1234567890ab",
  "merchant_order_id": "ORDER-124",
  "previous_status": "processing",
  "status": "completed",
  "status_version": 3,
  "fiat": "RUB",
  "amount_fiat": 5000,
  "amount_usdt": 62.81,
  "rate": 79.60,
  "merchant_amount_usdt": "59.67336683",
  "client_name": null,
  "expected_sender_name": null,
  "metadata": { "product_id": "sku_42" },
  "is_test": false,
  "event_created_at": "2026-01-01T00:00:00.000Z",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

POST https://merchant.com/webhook
X-Signature: <hmac_sha256_hex>
Content-Type: application/json

{
  "event": "deal.created",
  "deal_uuid": "1c9b7d40-52f1-4d0a-9d75-1f3d0c8a44e1",
  "deal_id": "1c9b7d40-52f1-4d0a-9d75-1f3d0c8a44e1",
  "merchant_order_id": "ORDER-TRY-5501",
  "previous_status": null,
  "status": "waiting_payment",
  "status_version": 1,
  "fiat": "TRY",
  "amount_fiat": 4500,
  "amount_usdt": 129.31,
  "rate": 34.80,
  "client_name": "Mehmet Yilmaz",
  "expected_sender_name": "Mehmet Yilmaz",
  "metadata": {},
  "is_test": false,
  "timestamp": "2026-01-01T00:00:00.000Z"
}

{
  "event": "deal.completed",
  "deal_uuid": "7a2e5f11-6c30-4b8e-a1f9-c0a4b2d8e5f6",
  "deal_id": "7a2e5f11-6c30-4b8e-a1f9-c0a4b2d8e5f6",
  "merchant_order_id": "ORDER-EGP-7712",
  "previous_status": "processing",
  "status": "completed",
  "status_version": 3,
  "fiat": "EGP",
  "amount_fiat": 12000,
  "amount_usdt": 243.90,
  "rate": 49.20,
  "client_name": "Ahmed Hassan Ali",
  "expected_sender_name": "Ahmed Hassan Ali",
  "metadata": {},
  "is_test": false,
  "timestamp": "2026-01-01T00:05:00.000Z"
}

const crypto = require("crypto");

// rawBody — оригинальный Buffer/строка тела запроса.
// В Express: app.use(express.json({ verify: (req, _res, buf) => (req.rawBody = buf) }));
const expected = crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");

const signature = req.headers["x-signature"];
if (
  !signature ||
  expected.length !== signature.length ||
  !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
) {
  throw new Error("Invalid signature");
}

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key"
  }
}

curl -X POST https://botonpay.org/api/public/v1/deals \
  -H "Authorization: Bearer bp_live_..." \
  -H "Idempotency-Key: 8b3f4c02-3f6f-4c88-9e02-0b3e9b3e0e7a" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "ORDER-124",
    "fiat": "RUB",
    "amount_fiat": 5000,
    "callback_url": "https://merchant.com/webhook"
  }'

const res = await fetch("https://botonpay.org/api/public/v1/deals", {
  method: "POST",
  headers: {
    "Authorization": "Bearer bp_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    merchant_order_id: "ORDER-124",
    fiat: "RUB",
    amount_fiat: 5000,
    callback_url: "https://merchant.com/webhook",
  }),
});
const data = await res.json();
if (!data.success) throw new Error(data.error.message);
console.log(data.deal.payment_url);

import axios from "axios";
const { data } = await axios.post("https://botonpay.org/api/public/v1/deals", {
  merchant_order_id: "ORDER-124",
  fiat: "RUB",
  amount_fiat: 5000,
}, { headers: { Authorization: "Bearer bp_live_..." } });
console.log(data.deal.payment_url);

const res = await fetch("https://botonpay.org/api/public/v1/deals", {
  method: "POST",
  headers: { "Authorization": "Bearer bp_live_...", "Content-Type": "application/json" },
  body: JSON.stringify({ merchant_order_id: "ORDER-124", fiat: "RUB", amount_fiat: 5000 }),
});
console.log(await res.json());

import requests
r = requests.post(
    "https://botonpay.org/api/public/v1/deals",
    json={"merchant_order_id": "ORDER-124", "fiat": "RUB", "amount_fiat": 5000},
    headers={"Authorization": "Bearer bp_live_..."},
    timeout=30,
)
print(r.json()["deal"]["payment_url"])

<?php
$ch = curl_init("https://botonpay.org/api/public/v1/deals");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer bp_live_...",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "merchant_order_id" => "ORDER-124",
    "fiat" => "RUB",
    "amount_fiat" => 5000,
  ]),
]);
$data = json_decode(curl_exec($ch), true);
echo $data["deal"]["payment_url"];

package main

import (
  "bytes"; "encoding/json"; "net/http"
)

func main() {
  body, _ := json.Marshal(map[string]any{
    "merchant_order_id": "ORDER-124",
    "fiat": "RUB",
    "amount_fiat": 5000,
  })
  req, _ := http.NewRequest("POST", "https://botonpay.org/api/public/v1/deals", bytes.NewReader(body))
  req.Header.Set("Authorization", "Bearer bp_live_...")
  req.Header.Set("Content-Type", "application/json")
  http.DefaultClient.Do(req)
}

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
  new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "bp_live_...");
var payload = new StringContent(
  System.Text.Json.JsonSerializer.Serialize(new {
    merchant_order_id = "ORDER-124", fiat = "RUB", amount_fiat = 5000
  }),
  System.Text.Encoding.UTF8, "application/json");
var res = await http.PostAsync("https://botonpay.org/api/public/v1/deals", payload);
Console.WriteLine(await res.Content.ReadAsStringAsync());

// Node.js / Express
import crypto from "crypto";

app.post("/webhook", express.raw({ type: "*/*" }), (req, res) => {
  const signature = req.header("X-Signature") || "";
  const expected = crypto
    .createHmac("sha256", process.env.BOTONPAY_WEBHOOK_SECRET)
    .update(req.body)              // именно сырой Buffer, не JSON.parse
    .digest("hex");

  const a = Buffer.from(signature), b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send("invalid signature");
  }

  const event = JSON.parse(req.body.toString("utf8"));
  // event.event: deal.paid | deal.completed | deal.cancelled | payout.completed ...
  res.send("ok");                  // отвечайте 2xx, иначе будет retry
});

# Python / FastAPI
import hmac, hashlib, os
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

@app.post("/webhook")
async def webhook(request: Request):
    raw = await request.body()
    signature = request.headers.get("X-Signature", "")
    expected = hmac.new(
        os.environ["BOTONPAY_WEBHOOK_SECRET"].encode(), raw, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(signature, expected):
        raise HTTPException(status_code=401, detail="invalid signature")
    event = await request.json()
    return {"ok": True}

# Python — массовая выплата из CSV
import csv, os, requests

API = "https://botonpay.org/api/public/v1/payouts"
HEADERS = {"Authorization": f"Bearer {os.environ['BOTONPAY_API_KEY']}"}

with open("payouts.csv", newline="", encoding="utf-8") as f:
    for i, row in enumerate(csv.DictReader(f), start=1):
        body = {
            "currency": row["currency"],
            "amount": float(row["amount"]),
            "payment_method": row["payment_method"],
            "merchant_order_id": row.get("merchant_order_id") or f"BULK-{i}",
            "recipient": {
                "full_name": row["full_name"],
                "card_number": row.get("card_number") or None,
                "phone": row.get("phone") or None,
                "iban": row.get("iban") or None,
                "bank_name": row.get("bank_name") or None,
            },
        }
        r = requests.post(API, json=body, headers={
            **HEADERS, "Idempotency-Key": body["merchant_order_id"]
        }, timeout=30)
        print(body["merchant_order_id"], r.status_code, r.json())

// Node.js — массовая выплата из массива
const rows = require("./payouts.json");

for (const [i, row] of rows.entries()) {
  const orderId = row.merchant_order_id ?? `BULK-${i + 1}`;
  const res = await fetch("https://botonpay.org/api/public/v1/payouts", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BOTONPAY_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": orderId,
    },
    body: JSON.stringify({ ...row, merchant_order_id: orderId }),
  });
  console.log(orderId, res.status, await res.json());
}

POST https://botonpay.org/api/public/v1/payouts
Authorization: Bearer bp_live_...
Content-Type: application/json
Idempotency-Key: payout-merchant-10001

{
  "merchant_order_id": "PAYOUT-10001",
  "currency": "KZT",
  "amount": 150000,
  "payment_method": "card",
  "bank_code": "kaspi",
  "recipient": {
    "full_name": "IVAN IVANOV",
    "card_number": "4400123412341234",
    "phone": "+77001234567"
  },
  "callback_url": "https://merchant.example.com/webhooks/botonpay",
  "customer_id": "customer-789",
  "metadata": { "user_id": "789" },
  "is_test": false
}

{
  "full_name": "IVAN IVANOV",
  "card_number": "4400123412341234",
  "phone": "+77001234567"
}

{ "full_name": "IVAN IVANOV", "phone": "+77001234567" }

{ "full_name": "IVAN IVANOV", "phone": "+79991234567" }

{ "full_name": "RAHUL SHARMA", "upi_id": "rahul@upi" }

{
  "full_name": "JOHN SMITH",
  "iban": "GE29NB0000000101904917",
  "bank_name": "Bank of Georgia",
  "swift": "BAGAGE22"
}

{
  "success": true,
  "payout": {
    "id": "927f5c36-57bd-4f90-a817-a1b5b67af421",
    "merchant_order_id": "PAYOUT-10001",
    "status": "pending",
    "currency": "KZT",
    "amount": 150000,
    "fee": 3000,
    "total_debit": 153000,
    "payment_method": "card",
    "bank_code": "kaspi",
    "recipient": { "full_name": "IVAN IVANOV", "card_number_masked": "440012******1234" },
    "expires_at": "2026-07-16T10:30:00.000Z",
    "is_test": false
  }
}

{
  "success": false,
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency-Key was already used with different request parameters"
  }
}

GET https://botonpay.org/api/public/v1/payouts/927f5c36-57bd-4f90-a817-a1b5b67af421
Authorization: Bearer bp_live_...

{
  "success": true,
  "payout": {
    "id": "927f5c36-57bd-4f90-a817-a1b5b67af421",
    "merchant_order_id": "PAYOUT-10001",
    "status": "processing",
    "currency": "KZT",
    "amount": 150000,
    "fee": 3000,
    "total_debit": 153000,
    "payment_method": "card",
    "bank_code": "kaspi",
    "recipient": { "full_name": "IVAN IVANOV", "card_number_masked": "440012******1234" },
    "customer_id": "customer-789",
    "created_at": "2026-07-16T10:00:00.000Z",
    "updated_at": "2026-07-16T10:05:00.000Z",
    "expires_at": "2026-07-16T10:30:00.000Z",
    "is_test": false
  }
}

GET https://botonpay.org/api/public/v1/payouts/by-merchant-order/PAYOUT-10001
Authorization: Bearer bp_live_...

GET https://botonpay.org/api/public/v1/payouts?status=completed&currency=KZT&page=1&per_page=20
Authorization: Bearer bp_live_...

{
  "success": true,
  "data": [
    {
      "id": "927f5c36-57bd-4f90-a817-a1b5b67af421",
      "merchant_order_id": "PAYOUT-10001",
      "status": "completed",
      "currency": "KZT",
      "amount": 150000,
      "fee": 3000,
      "total_debit": 153000,
      "payment_method": "card",
      "created_at": "2026-07-16T10:00:00.000Z",
      "completed_at": "2026-07-16T10:10:00.000Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 }
}

POST https://botonpay.org/api/public/v1/payouts/927f5c36-57bd-4f90-a817-a1b5b67af421/cancel
Authorization: Bearer bp_live_...
Content-Type: application/json

{ "reason": "customer_cancelled" }

{
  "success": true,
  "payout": {
    "id": "927f5c36-57bd-4f90-a817-a1b5b67af421",
    "merchant_order_id": "PAYOUT-10001",
    "status": "cancelled",
    "cancel_reason": "customer_cancelled",
    "cancelled_at": "2026-07-16T10:03:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "conflict",
    "message": "Payout is already being processed",
    "details": {
      "code": "payout_cannot_be_cancelled",
      "status": "processing"
    }
  }
}

POST https://botonpay.org/api/public/v1/payouts/{id}/dispute
Authorization: Bearer bp_live_...
Content-Type: application/json

{
  "reason": "Получатель не увидел зачисление, прошло 3 часа",
  "files": [
    { "name": "screenshot.png", "type": "image/png", "data": "<base64>" }
  ]
}

{
  "success": true,
  "payout_id": "927f5c36-57bd-4f90-a817-a1b5b67af421",
  "dispute": {
    "dispute_id": "5f1c...",
    "status": "open",
    "reason": "Получатель не увидел зачисление, прошло 3 часа",
    "resolution_note": null,
    "evidence_count": 1,
    "created_at": "2026-08-19T09:12:00.000Z",
    "resolved_at": null,
    "payout_status": "completed"
  }
}

POST https://botonpay.org/api/public/v1/sandbox/payouts/{id}/status
Authorization: Bearer bp_test_...
Content-Type: application/json

{ "status": "completed", "proof_url": "https://example.com/proof.jpg" }

{
  "success": true,
  "payout": {
    "id": "927f5c36-57bd-4f90-a817-a1b5b67af421",
    "status": "completed",
    "is_test": true
  }
}

Content-Type: application/json
X-BotonPay-Timestamp: 1784196600
X-BotonPay-Signature: sha256=...
X-BotonPay-Event: payout.completed
X-BotonPay-Event-Id: evt_18e2f0a0a8

{
  "event": "payout.completed",
  "event_id": "evt_18e2f0a0a8",
  "created_at": "2026-07-16T10:10:00.000Z",
  "payout": {
    "id": "927f5c36-57bd-4f90-a817-a1b5b67af421",
    "merchant_order_id": "PAYOUT-10001",
    "status": "completed",
    "amount": 150000,
    "fee": 3000,
    "total_debit": 153000,
    "currency": "KZT",
    "completed_at": "2026-07-16T10:10:00.000Z"
  }
}

signature = HMAC_SHA256(webhook_secret, timestamp + "." + raw_body)
X-BotonPay-Signature: sha256=<SIGNATURE>

fee = amount × percentage + fixed_fee
total_debit = amount + fee

// Пример:
amount       = 150000 KZT
percentage   = 2%
fixed_fee    = 0 KZT
fee          = 3000 KZT
total_debit  = 153000 KZT

{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient merchant balance",
    "details": { "currency": "KZT", "required": 153000, "available": 120000 }
  }
}

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": { "field": "recipient.card_number", "reason": "invalid_card_number" }
  }
}

curl -X POST "https://botonpay.org/api/public/v1/payouts" \
  -H "Authorization: Bearer bp_test_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-test-10001" \
  -d '{
    "merchant_order_id": "PAYOUT-10001",
    "currency": "KZT",
    "amount": 150000,
    "payment_method": "card",
    "bank_code": "kaspi",
    "recipient": {
      "full_name": "IVAN IVANOV",
      "card_number": "4400123412341234"
    },
    "callback_url": "https://merchant.example.com/webhooks/botonpay",
    "is_test": true
  }'

const response = await fetch(
  "https://botonpay.org/api/public/v1/payouts",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer bp_test_xxxxxxxxx",
      "Content-Type": "application/json",
      "Idempotency-Key": "payout-test-10001",
    },
    body: JSON.stringify({
      merchant_order_id: "PAYOUT-10001",
      currency: "KZT",
      amount: 150000,
      payment_method: "card",
      bank_code: "kaspi",
      recipient: {
        full_name: "IVAN IVANOV",
        card_number: "4400123412341234",
      },
      callback_url: "https://merchant.example.com/webhooks/botonpay",
      is_test: true,
    }),
  }
);

const result = await response.json();
if (!response.ok) {
  throw new Error(result?.error?.message || "Failed to create PayOut");
}
console.log(result.payout);

created
  → pending
  → searching_trader
  → assigned
  → processing
  → proof_uploaded
  → completed

// Отмена до назначения трейдера:
created / pending / searching_trader → cancelled

// С апелляцией:
processing / proof_uploaded → dispute → completed / rejected / refunded