Платёжные сессии v2
Создание и чтение авторитетной сессии.
POST /v2/payment-sessions
Нужны X-Api-Key, Idempotency-Key и JSON. Сохраните точный запрос и ключ до отправки. При неизвестном результате повторяйте тот же запрос; не обходите конфликт новым ключом. Не передавайте projectId, mode, ID кошелька, маршрут или URL возврата: их задают ключ и проект.
curl https://api.bramapay.com/v2/payment-sessions \
--header "X-Api-Key: YOUR_PROJECT_SECRET_KEY" \
--header "Idempotency-Key: order-demo-1042-v1" \
--header "Content-Type: application/json" \
--data '{"amountUsd":"25.00","currency":"USD","externalId":"order-demo-1042"}'| Поле | Контракт |
|---|---|
amountUsd | Положительная десятичная строка USD, до 6 дробных цифр; обязательна для MERCHANT. 25.0000001 отклоняется. |
currency | Обязательное значение USD. |
externalId | Обязательная строка 1–200 символов: ID заказа продавца. |
expiresInSeconds | Необязательное целое 1–86400; по умолчанию 1800 секунд. Выбор маршрута не продлевает срок. |
displayOrderNumber | Необязательный текст до 100 Unicode-символов. |
description | Необязательный неизменяемый текст до 1000 Unicode-символов; не меняет расчёт суммы. |
feePayer, pricingVersion, baseAmountUsd | Явная оплата покупателем: BUYER, BUYER_FEE_V1, положительная базовая сумма до 6 дробных цифр; 25.0000001 отклоняется; исключите amountUsd. По умолчанию MERCHANT. |
merchantCustomer | Необязательный закрытый объект клиента для депозита или заказа; не данные checkout или доказательства платежа. |
merchantCustomer принимает только {customerId, depositId, email?} или {customerId, orderId, orderNumber, email?}. customerId: 1–100 ASCII-букв/цифр/подчёркиваний/дефисов; для заказа также null. depositId/orderId — UUID. orderNumber непустой, до 100 символов без управляющих символов. email необязателен/null либо корректный адрес до 254 символов. Лишние свойства запрещены. Не передавайте произвольные или чувствительные данные.
GET /v2/payment-sessions/:id
Используйте тот же секретный ключ проекта/режима. id — UUID сессии. Чужой проект/контекст возвращает not found. Создание и чтение возвращают следующие поля; дополнительные поля тарификации зависят от контракта. Денежные значения — строки.
| Поле | Контракт |
|---|---|
sessionId, projectId, externalId | Идентификаторы сессии, проекта и заказа. |
mode, paymentMode | TEST или LIVE; оба поля содержат сохранённый режим. |
status | OPEN, PAID, EXPIRED. Закрытие передаётся отдельно в closedAt; CONFIRMING/CLOSED — фильтры кабинета, а не значения этого поля. |
amountUsd, currency, pricingVersion, feePayer, pricing | Десятичная сумма и условный снимок тарификации; сверяйте по сохранённому контракту. |
serverNow, expiresAt, createdAt, paidAt, closedAt | Серверное время, срок и даты жизненного цикла; null, если событие не наступило. |
monitoringComplete, pendingSettlement, isFinal | Отдельные признаки мониторинга и окончательности; истечение срока не доказывает неоплату. |
settlementState | WAITING_SETTLEMENT, STOPPED_BY_POLICY, COMPLETE, MONITORING. |
ratePolicy, discoveryPolicy, discoveryStopped | Сохранённые политики и состояние обнаружения; не основание просить новый перевод. |
successUrl, cancelUrl, checkoutUrl | Сохранённые URL возврата и секретный capability-URL checkout. |
winningAttemptId | ID победившего счёта/попытки либо null. |
routes | Доступные сейчас объекты {asset, network, networkKey, available}; массив может быть пустым. |
attempts | Сохранённые неизменяемые инструкции и мониторинг; см. ниже. |
receipts | Записи наблюдаемых переводов; сами по себе не разрешают выдачу заказа. |
Попытка содержит attemptId, invoiceId, asset, network, networkKey, address, amount, requestedAmount, status, expiresAt, txHash, quote, monitoringState, monitoringComplete. Запись перевода: receiptId, attemptId, invoiceId, paymentId, asset, network, amount, txHash, status, receivedAt. Показывайте точную сумму токена из ответа; не вычисляйте её из amountUsd. Новые hosted-попытки принимают только USDT; старые USDC читаются. Пустой routes означает недоступность.
При политике проекта amountUsd остаётся базой заказа, baseAmountUsd/payableAmountUsd разделяют базу и итог. У явного BUYER_FEE_V1 другой контракт. См. оплату комиссии покупателем. Выдавайте заказ только после проверенного payment_session.paid, авторизованного чтения PAID, сверки заказа/проекта/режима/валюты/цены и надёжной дедупликации события и заказа. Redirect, тест связи и дочерний счёт не разрешают отдельную выдачу.