Швидкий старт

Створіть тестову сесію v2 та перевірте замовлення на сервері.

Створіть тестову платіжну сесію v2, відкрийте сторінку оплати й підтвердьте одне тестове замовлення. Потрібен сервер магазину: запити, зберігання секретів і перевірка оплати виконуються на ньому. Це навчальний приклад, а не готовий застосунок. До обробки подій реалізуйте повну перевірку підпису. Повний контракт наведено в посібнику із сесій; рахунки v1 підтримуються для наявних інтеграцій.

1. Підготуйте проєкт

Зареєструйтеся, підтвердьте email, виберіть проєкт і режим Test. Зареєструйте підконтрольний вам тестовий гаманець і явно дозвольте USDT у TRON Shasta. Реєстрація гаманця Live не створює реєстрацію Test. Не передавайте приватний ключ чи фразу відновлення.

Задайте successUrl, cancelUrl і точні allowedRedirectDomains. Додайте активну публічну HTTPS-адресу вебхука, збережіть одноразовий secret і keyId. Реалізуйте перевірку підпису до перевірки з'єднання. Створіть секретний API-ключ Test для цього проєкту та зберігайте його на сервері. Див. налаштування проєкту і URL повернення.

Режим Test має бути доступний. Якщо він недоступний, зверніться до підтримки й перевіряйте обробник на локальних прикладах; не переходьте автоматично на Live. Тестові токени не оплачують реальні замовлення й не поповнюють сервісний баланс Live.

2. Створіть одну тестову сесію

До надсилання збережіть замовлення, очікувані проєкт і режим, точне тіло запиту й ключ ідемпотентності. Після тайм-ауту з невідомим результатом повторюйте те саме тіло з тим самим ключем. Не обходьте конфлікт новим ключем. Грошові значення передаються десятковими рядками, а не числами з рухомою комою.

curl --request POST 'https://api.bramapay.com/v2/payment-sessions' \
  --header 'X-Api-Key: YOUR_TEST_PROJECT_SECRET_KEY' \
  --header 'Idempotency-Key: order-demo-1042-attempt-1' \
  --header 'Content-Type: application/json' \
  --data '{"amountUsd":"25.00","currency":"USD","externalId":"order-demo-1042"}'

Проєкт і режим визначає ключ. Не передавайте projectId, mode, ID гаманців чи перевизначення URL повернення. Додаткові поля й варіанти комісії описані в контракті сесії та правилах комісії покупця.

3. Збережіть відповідь

До відкриття оплати зв'яжіть із замовленням ID сесії, проєкт, режим, зовнішній ID замовлення, валюту, суму й незмінний знімок ціни. Нижче часткова вигадана відповідь, а не повна схема чи реквізити: домен зарезервований для прикладів, токен доступу несправжній.

{
  "sessionId": "00000000-0000-4000-8000-000000000001",
  "projectId": "prj_00000000000000000000000000000000",
  "externalId": "order-demo-1042",
  "mode": "TEST",
  "paymentMode": "TEST",
  "amountUsd": "25",
  "currency": "USD",
  "status": "OPEN",
  "checkoutUrl": "https://checkout.example/en/checkout/00000000-0000-4000-8000-000000000001#token=EXAMPLE_NOT_A_REAL_CAPABILITY",
  "routes": [],
  "attempts": []
}

routes: [] означає відсутність доступного маршруту. Не вигадуйте його й не просіть переказ. Нові спроби на розміщеній сторінці оплати використовують USDT; запис у реєстрі не гарантує доступності для сесії. Раніше видані спроби зберігають реквізити.

4. Відкрийте оплату

Використовуйте повернений checkoutUrl без змін. Фрагмент містить токен доступу: виключіть повний URL із журналів та аналітики. Секретний API-ключ не має потрапляти до браузера. Не складайте посилання самостійно й не переносьте токен у рядок запиту.

Покупець вибирає доступну мережу й один раз надсилає точну суму на поточну адресу, у вказаному токені та до строку. QR містить лише адресу. Не округлюйте, не розбивайте переказ, не обчислюйте суму токенів самостійно й не просіть доплатити різницю. Зміна маршруту не подовжує строк. Див. перший тестовий платіж.

5. Перевірте підтвердження

До обробки JSON виконайте повну перевірку початкового тіла: обмежте розмір, перевірте час у межах 300 секунд, підписані ID і тип події, вибір секрету за ID ключа, точний конверт протоколу v2 та HMAC порівнянням за сталий час. Вимагайте X-Idempotency-Key === X-Event-Id. Зберігайте нескомпрометовані старі секрети для наявних доставок. Простір підпису — буквально vaultless.webhook (історична назва протоколу, змінювати її не потрібно); версії API та протоколу вебхуків незалежні.

Подія оплати сесії — лише payment_session.paid. integration.test, webhook.test, перехід браузера й подія дочірнього рахунку не дозволяють виконання замовлення сесії. Подія Test не оплачує замовлення Live. Після перевірки підпису та структури отримайте сесію зі свого сервера:

curl 'https://api.bramapay.com/v2/payment-sessions/SESSION_ID' \
  --header 'X-Api-Key: YOUR_TEST_PROJECT_SECRET_KEY'

Вимагайте status === "PAID" з авторизованої відповіді та збіг збережених сесії, замовлення, проєкту, режиму, валюти й ціни за початковим контрактом. Порівнюйте десяткові значення точно. За комісії з налаштувань проєкту amountUsd зберігає вартість замовлення; явний BUYER_FEE_V1 має іншу семантику. Не плутайте вартість замовлення, суму USD до сплати й точну суму токенів.

Зберігайте дедуплікацію події та одноразове виконання замовлення в одній транзакції БД, з унікальними обмеженнями для події та замовлення й чергою вихідних завдань. Повертайте 2xx після надійного збереження; тимчасові помилки читання чи БД мають допускати повтор. Див. підтвердження замовлення і повторну доставку.

6. Перед переходом на Live

Налаштуйте окремі гаманці, секрети й вебхуки Live; успішно перевірте кожну поточну адресу та конфігурацію Live. Перевірте готовність проєкту, маршрути й чинну ставку. Створення нових платежів Live дозволено лише за B + C > 0, де B — фактичний сервісний баланс, C — схвалений кредит. Типово C = 0. Уже видані платежі продовжують оброблятися та можуть збільшити борг понад поріг. Для поповнення використовуйте окремі реквізити Billing.

На локальних прикладах перевірте неправильні підписи, режим, замовлення й тип події, повтори подій і виконання, відсутність маршрутів, завершення строку та невідомий результат створення. Звичайний 503 не доводить відмови: потрібен перевірений PAYMENT_CREATION_DECLINED зі збігом ідентичності, квитанцією відмови, retryable: false і sessionCreated: false. Збережіть квитанцію.

Таймер не доводить остаточності: своєчасний переказ може підтвердитися пізніше. Використовуйте серверний статус, monitoringComplete та isFinal. Помилкові, пізні й додаткові перекази потребують розгляду; не запитуйте гроші повторно автоматично й не обіцяйте повернення. Успішний тест не доводить доступності Live.