Перейти к основному содержимому

Payments API

API для обработки платежей и финансовых операций.

Обзор​

Payments API интегрируется с различными платежными системами (ЮKassa, Stripe) и обеспечивает безопасную обработку платежей.

Поддерживаемые платежные системы​

ЮKassa​

  • Банковские карты
  • Электронные кошельки
  • Интернет-банкинг
  • Наличные через терминалы

Stripe​

  • Международные карты
  • Apple Pay / Google Pay
  • SEPA переводы

Структура платежа​

interface Payment {
  id: string;
  order_id: string;
  amount: number;
  currency: string;
  status: PaymentStatus;
  payment_method: string;
  provider: 'yukassa' | 'stripe';
  provider_payment_id: string;
  created_at: string;
  completed_at?: string;
}

Статусы платежа​

  • pending - Ожидает обработки
  • processing - В процессе
  • succeeded - Успешно завершен
  • failed - Ошибка
  • cancelled - Отменен
  • refunded - Возвращен

Создание платежа​

// POST /api/payments
{
  "order_id": "uuid",
  "amount": 5000,
  "currency": "RUB",
  "payment_method": "bank_card",
  "return_url": "https://example.com/success",
  "description": "Оплата заказа #123"
}

Обработка результата​

// Успешный платеж
{
  "id": "uuid",
  "status": "succeeded",
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://..."
  }
}

Webhooks​

ЮKassa webhook​

{
  "type": "notification",
  "event": "payment.succeeded",
  "object": {
    "id": "payment_id",
    "status": "succeeded",
    "amount": {
      "value": "100.00",
      "currency": "RUB"
    }
  }
}

Возвраты​

// POST /api/payments/{id}/refund
{
  "amount": 5000,
  "reason": "Отмена заказа клиентом"
}

Комиссии​

Система автоматически рассчитывает и удерживает комиссии:

  • Комиссия маркетплейса
  • Комиссия платежной системы
  • НДС (при необходимости)
{
  "amount": 5000,
  "marketplace_commission": 250,
  "payment_fee": 100,
  "net_amount": 4650
}