Примеры и кейсы АТОЛ Pay
Готовые кейсы интеграции с АТОЛ Pay Ecom - интернет-магазин, бронирование, SaaS-подписка, оплата в один клик - с кодом на Node.js, Python и PHP.
Кейс 1. Интернет-магазин: оплата корзины с чеком
Классический сценарий: покупатель оформил корзину, магазин регистрирует одностадийный платеж с фискализацией и ждет callback.
// Базовый 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; // редиректим покупателя сюда
}import os
import requests
# Базовый URL - из конфига; по умолчанию sandbox, прод включается переменной
BASE = os.environ.get("ATOL_PAY_BASE_URL", "https://croc-sandbox-api-mobile.atolpay.ru")
TOKEN = os.environ["ATOL_PAY_TOKEN"]
def create_payment(order: dict) -> str:
payload = {
"amount": order["total_kopecks"],
"orderId": order["id"],
"sessionType": "oneStep",
"additionalProps": {
"returnUrl": f"https://shop.example.com/orders/{order['id']}/return",
"notificationUrl": f"https://shop.example.com/webhooks/atolpay?orderId={order['id']}",
},
"receipt": {
"buyer": {"email": order["email"]},
"positions": [
{
"name": item["title"],
"price": item["price_kopecks"],
"quantity": item["qty"] * 1000,
"measure": 0,
"paymentMethod": 3,
"paymentSubject": 0,
"tax": 0,
}
for item in order["items"]
],
"providerId": 100,
"sno": 1,
},
"paymentMethods": [{"paymentType": "card", "bankId": 100}],
}
res = requests.post(
f"{BASE}/v1/ecom/payments",
json=payload,
headers={"Authorization": f"Bearer {TOKEN}"},
timeout=30,
)
data = res.json()
if data.get("status") == "error":
raise RuntimeError(f"{data['errorCode']}: {data['errorMessage']}")
return data["data"]["paymentUrls"]["main"]<?php
// Базовый URL - из конфига; по умолчанию sandbox, прод включается переменной
$base = getenv('ATOL_PAY_BASE_URL') ?: 'https://croc-sandbox-api-mobile.atolpay.ru';
$token = getenv('ATOL_PAY_TOKEN');
function createPayment(array $order): string
{
global $base, $token;
$payload = [
'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']}",
],
'paymentMethods' => [
['paymentType' => 'card', 'bankId' => 100],
],
'receipt' => [
'buyer' => ['email' => $order['email']],
'positions' => array_map(static fn (array $item): array => [
'name' => $item['title'],
'price' => $item['priceKopecks'],
'quantity' => $item['qty'] * 1000,
'measure' => 0,
'paymentMethod' => 3,
'paymentSubject' => 0,
'tax' => 0,
], $order['items']),
'providerId' => 100,
'sno' => 1,
],
];
$ch = curl_init($base . '/v1/ecom/payments');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $token,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($data['status'] ?? '') === 'error') {
throw new RuntimeException($data['errorCode'] . ': ' . $data['errorMessage']);
}
return $data['data']['paymentUrls']['main'];
}curl -X POST "https://croc-sandbox-api-mobile.atolpay.ru/v1/ecom/payments" \
-H "Authorization: Bearer $ATOL_PAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 250000,
"orderId": "order-2025-0001",
"sessionType": "oneStep",
"additionalProps": {
"returnUrl": "https://shop.example.com/return",
"notificationUrl": "https://shop.example.com/webhooks/atolpay"
},
"receipt": {
"buyer": { "email": "buyer@example.com" },
"positions": [{
"name": "Кроссовки", "price": 250000, "quantity": 1000,
"measure": 0, "paymentMethod": 3, "paymentSubject": 0, "tax": 0
}],
"providerId": 100,
"sno": 1
},
"paymentMethods": [{ "paymentType": "card", "bankId": 100 }]
}'Обработчик callback (Node.js / Express):
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. Бронирование: двухстадийный платеж
Отель или сервис бронирования замораживает средства при бронировании и списывает их после подтверждения (либо отменяет без комиссии).
// 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: подписка с пробным периодом
// 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. Оплата в один клик по сохраненной карте
// 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. Частичный возврат с чеком
// 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 и частичными возвратами». Порядок кусков кода без ассистента - в быстром старте.