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

Примеры и кейсы АТОЛ Pay

Готовые кейсы интеграции с АТОЛ Pay Ecom - интернет-магазин, бронирование, SaaS-подписка, оплата в один клик - с кодом на Node.js, Python и PHP.

Кейс 1. Интернет-магазин: оплата корзины с чеком

Классический сценарий: покупатель оформил корзину, магазин регистрирует одностадийный платеж с фискализацией и ждет callback.

js
// Базовый URL - из конфига; по умолчанию sandbox, прод включается переменной
const BASE = process.env.ATOL_PAY_BASE_URL ?? 'https://croc-sandbox-api-mobile.atolpay.ru';
const TOKEN = process.env.ATOL_PAY_TOKEN;

async function createPayment(order) {
  const res = await fetch(`${BASE}/v1/ecom/payments`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: order.totalKopecks,           // сумма в копейках
      orderId: order.id,                    // ваш идентификатор заказа
      sessionType: 'oneStep',
      additionalProps: {
        returnUrl: `https://shop.example.com/orders/${order.id}/return`,
        notificationUrl: `https://shop.example.com/webhooks/atolpay?orderId=${order.id}`,
      },
      receipt: {
        buyer: { email: order.email },
        positions: order.items.map((item) => ({
          name: item.title,
          price: item.priceKopecks,
          quantity: item.qty * 1000,        // количество в тысячных
          measure: 0,                       // поштучно
          paymentMethod: 3,                 // полный расчет
          paymentSubject: 0,                // товар (см. словарь /receipts/dictionaries)
          tax: 0,                           // НДС 20%
        })),
        providerId: 100,                    // АТОЛ Онлайн
        sno: 1,                             // УСН (доходы)
      },
      paymentMethods: [
        { paymentType: 'card', bankId: 100 },
        { paymentType: 'sbp', bankId: 100 },
      ],
    }),
  });

  const data = await res.json();
  // Ответ: { status: "success", data: { orderId, amount, paymentUrls: {...} } }
  if (data.status === 'error') {
    throw new Error(`${data.errorCode}: ${data.errorMessage}`);
  }
  return data.data.paymentUrls.main; // редиректим покупателя сюда
}

Обработчик callback (Node.js / Express):

js
app.post('/webhooks/atolpay', express.json(), async (req, res) => {
  const event = req.body;
  // Идемпотентность: одно событие может прийти повторно
  if (await alreadyProcessed(event.orderId, event.type, event.paymentStatus)) {
    return res.sendStatus(200);
  }

  switch (event.type) {
    case 'payment':
      if (event.status === 'success' && event.paymentStatus === 1) {
        await markOrderPaid(event.orderId, event.paidAt);
      } else if (event.status === 'fail') {
        await markOrderFailed(event.orderId, event.errorCode);
      }
      break;
    case 'refund':
    case 'cancel':
      await markOrderRefunded(event.orderId, event.canceledAt);
      break;
    case 'fiscal':
      await saveReceipt(event.orderId, event.receiptId, event.receiptType);
      break;
  }
  res.sendStatus(200); // отвечаем быстро, тяжелое - в фоне
});

Кейс 2. Бронирование: двухстадийный платеж

Отель или сервис бронирования замораживает средства при бронировании и списывает их после подтверждения (либо отменяет без комиссии).

js
// 1. Регистрация с заморозкой
const { data } = await api.post('/v1/ecom/payments', {
  amount: 1200000, // 12 000 ₽
  orderId: bookingId,
  sessionType: 'twoStep',
  additionalProps: { returnUrl, notificationUrl },
});
const paymentUrl = data.paymentUrls.main;

// 2. Ждем callback первой стадии: paymentStatus === 11 (awaitingDeposit)

// 3а. Подтверждение брони -> списание (не позднее 7 суток!)
await api.post(`/v1/ecom/payments/${bookingId}/deposit`);

// 3б. Либо отмена брони -> отмена холда без комиссии
await api.post(`/v1/ecom/payments/${bookingId}/cancel`, {});

Поставьте в планировщик напоминание: если бронь не подтверждена за 6 суток - автоматически отмените платеж, иначе холд истечет сам, но клиентский опыт будет хуже.

Кейс 3. SaaS: подписка с пробным периодом

js
// 1. Один раз создаем план
const plan = await api.post('/v1/ecom/subscription-plans', {
  name: 'Pro, месяц',
  externalPlanId: 'pro-monthly',
  period: { months: 1 },
  trialPeriod: { days: 14 },
  data: {
    amount: 99000, // 990 ₽
    returnUrl: 'https://saas.example.com/billing/return',
    receipt: { providerId: 100, sno: 1 },
    items: [{
      name: 'Подписка Pro, 1 месяц', price: 99000, quantity: 1000, measure: 0,
      receipt: { paymentMethod: 3, paymentSubject: 4, tax: 0 }, // услуга
    }],
    merchant: { name: 'ООО СААС' },
    paymentMethods: [{ paymentType: 'card', bankId: 100 }],
  },
});

// 2. Для каждого клиента создаем подписку
const sub = await api.post('/v1/ecom/buyer-subscriptions/order', {
  externalPlanId: 'pro-monthly',
  orderId: `sub-${userId}-${Date.now()}`,
  notificationUrl: 'https://saas.example.com/webhooks/atolpay',
  buyer: { id: String(userId), email: userEmail },
});
// -> редирект клиента на sub.data.paymentUrls.main

// 3. Обрабатываем callback type=subscription
//    new/trial        -> активировать доступ
//    prolongation     -> продлить доступ
//    retry            -> предупредить клиента (retryNum попыток)
//    canceled         -> закрыть доступ

Кейс 4. Оплата в один клик по сохраненной карте

js
// 1. Список карт клиента
const { data } = await api.get(
  `/v1/ecom/payments/cards?buyerId=${buyerId}`,
);
const card = data.cards[0]; // { id, pan: '*4111', bindingId, bankId }

// 2. Регистрируем заказ с recurring: true и тем же buyerId
await api.post('/v1/ecom/payments', {
  amount, orderId, sessionType: 'oneStep',
  recurring: true,
  buyerId,
  additionalProps: { returnUrl, notificationUrl },
});

// 3. Списываем по привязке без платежной формы
await api.post(`/v1/ecom/payments/${orderId}/recurring/pay`, {
  bindingId: card.bindingId,
  buyerEmail: email,
});

Кейс 5. Частичный возврат с чеком

js
// 1. Какие позиции доступны к возврату
const { data } = await api.get(`/v1/ecom/payments/${orderId}/refund-items`);

// 2. Возвращаем одну позицию
await api.post(`/v1/ecom/payments/${orderId}/cancel`, {
  amount: 1000, // сумма возврата в копейках
  positions: [
    {
      parentItemId: data.positions[0].parentItemId,
      sum: 1000,
      quantity: 1000, // 1 штука в тысячных
    },
  ],
});
// Чек «Возврат прихода» уйдет автоматически (callback type=fiscal, receiptType=sell_refund)

Больше примеров

Готовый код на четырех языках выше - это и есть ручной быстрый старт. Нужен другой стек или сценарий - откройте сквозные кейсы или подключите MCP-сервер и попросите ассистента, например: «Напиши интеграцию АТОЛ Pay для Django с обработкой callback и частичными возвратами». Порядок кусков кода без ассистента - в быстром старте.