Платіжні сесії 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, тест зв’язку й дочірній рахунок не дозволяють окремої видачі.