Створення замовлень

3.1.3. Створення замовлень#

Ця сторінка містить всю документацію до відеоуроку, що пояснює просте створення замовлення через API та перевірку його статусу.

3.1.3.1. Відео#

3.1.3.2. Вимоги#

Необхідно для цієї серії уроків:

  • Бекенд торговця Талером
    Якщо вам потрібна допомога з використанням бекенду продавця вперше, ви можете переглянути навчальний посібник Вступ до роботи продавця.
  • Примірник гаманця Taler
    Інструкції з налаштування доступні на сайті https://wallet.taler.net.
  • Програмне забезпечення для управління REST API або відповідні навички програмування
    У цій серії відео ми будемо використовувати безкоштовне програмне забезпечення Insomnia, яке можна завантажити за посиланням https://insomnia.rest.

3.1.3.3. Повідомлення про демонстраційний бекенд#

Для цього підручника ви можете використовувати власний бекенд-сервіс продавця або онлайн-демонстраційний сервіс на https://backend.demo.taler.net/instances/sandbox/.

3.1.3.4. Обробка торгових платежів#

  1. Створення замовлення на платіж

Платежі в Taler базуються на замовленні, яке є машинозчитуваним описом бізнес-транзакції, за яку має бути здійснений платіж. Перед тим, як прийняти платіж в Талер як продавець, ви повинні створити таке замовлення.

Це робиться шляхом POST’у JSON-об’єкта до кінцевої точки API бекенда /private/orders. У полі order повинні бути вказані принаймні наступні поля:

  • сума: Сума до сплати, як рядок у форматі CURRENCY:DECIMAL_VALUE, наприклад EUR:10 для 10 євро або KUDOS:1.5 для 1.5 KUDOS.

  • суть: Короткий, зрозумілий для людини опис того, за що здійснюється платіж. Резюме має бути достатньо коротким, щоб вписатися в заголовок, хоча жорстких обмежень не існує.

  • fulfillment_url: URL-адреса, яка буде відображена після завершення оплати. Для цифрових товарів це має бути сторінка, яка відображає товар, що був придбаний. Після успішної оплати гаманець автоматично додає order_id як параметр запиту, а також session_sig для сесійних платежів (описано нижче).

Замовлення можуть мати набагато більше полів, див. Формат замовлення Taler. Під час відправлення замовлення ви також можете вказати додаткові деталі, такі як перевизначення тривалості відшкодування та інструкції з управління запасами. Вони рідко потрібні і не розглядаються в цьому підручнику; будь ласка, зверніться до довідкового посібника для отримання детальної інформації.

Мінімальний фрагмент Python для створення замовлення виглядатиме так:

>>> import requests
>>> body = dict(order=dict(amount="KUDOS:10",
...                        summary="Donation",
...                        fulfillment_url="https://example.com/thanks.html"),
...             create_token=False)
>>> response = requests.post("https://backend.demo.taler.net/instances/sandbox/private/orders",
...               json=body,
...               headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Бекенд заповнить деякі деталі, яких не вистачає в замовленні, наприклад, адресу екземпляра продавця. Повна інформація називається умовами контракту.

Примітка

Вищевказаний запит вимикає використання токенів претензій, встановлюючи опцію create_token у значення false. Якщо вам потрібні токени претензії, ви повинні скоригувати код, щоб сконструювати URI taler://pay/, наведений нижче, щоб включити токен претензії.

Після успішного POST на /private/orders буде повернуто JSON з одним полем order_id, яке містить рядок, що представляє ідентифікатор замовлення. Якщо ви також отримали токен претензії, будь ласка, перевірте, чи використовували ви запит, як описано вище.

Разом з «екземпляром» продавця ідентифікатор замовлення однозначно ідентифікує замовлення в бекенді продавця. Використовуючи ідентифікатор замовлення, ви можете тривіально сконструювати відповідний taler://pay/ URI, який має бути наданий гаманцю. Нехай example.com буде доменним ім’ям, з якого доступні публічні кінцеві точки екземпляра. Тоді URI для оплати в Taler буде просто taler://pay/example.com/$ORDER_ID/, де $ORDER_ID потрібно замінити на ідентифікатор замовлення, яке було повернуто.

Ви можете вказати URI taler:// як ціль посилання для відкриття гаманця Taler за схемою taler:// або помістити його в QR-код. Однак для веб-магазину найпростіший спосіб - просто перенаправити браузер на https://example.com/orders/$ORDER_ID. Ця сторінка запустить гаманець Taler. Тут бекенд генерує правильну логіку для запуску гаманця, підтримуючи різні типи існуючих гаманців Taler. Замість того, щоб створювати наведену вище URL-адресу вручну, її також можна отримати, перевіривши статус платежу, як описано в наступному розділі.

При ручному конструюванні цієї URL-адреси обов’язково додайте токен claim (якщо він не був відключений) і якщо бекенд працює без TLS, використовуйте taler+http:// (зверніть увагу, що останнє підтримується тільки гаманцями, що працюють в режимі налагодження).

Примітка

Тривіальний спосіб отримати правильний payment_redirect_url - перевірити статус платежу (див. нижче). Тож якщо ви все ще не знаєте, як його створити, ви можете просто попросити бекенд зробити це за вас. Однак у виробництві вам, ймовірно, варто створити його вручну і уникнути зайвих запитів до бекенду.

  1. Перевірка статусу платежу та запит на оплату

Знаючи ідентифікатор замовлення, статус платежу можна перевірити за допомогою кінцевої точки /private/orders/$ORDER_ID. Якщо платіж ще не завершено клієнтом, /private/orders/$ORDER_ID надасть фронтенду URL-адресу (під назвою payment_redirect_url), яка запустить гаманець клієнта для виконання платежу. По суті, це URL-адреса https://example.com/orders/$ORDER_ID, яку ми обговорювали вище.

>>> import requests
>>> r = requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders/" + order_id,
...                  headers={"Authorization": "Bearer secret-token:sandbox"})
>>> print(r.json())

Якщо поле order_status у відповіді має значення paid, ви не отримаєте payment_redirect_url, а натомість отримаєте інформацію про статус платежу, включно зі статусом оплати:

  • contract_terms: Повні умови контракту замовлення.

  • «Відшкодовано»: «істина», якщо за цю покупку було надано (можливо, часткове) відшкодування.

  • повернута_сума: Сума, яка була повернута

Після того, як фронтенд підтвердив, що платіж пройшов успішно, він, як правило, повинен запустити бізнес-логіку для виконання продавцем своїх зобов’язань за договором.

Примітка

Вам не потрібно продовжувати запити, щоб помітити зміни в статусі транзакції замовлення. Кінцеві точки підтримують довгі опитування, просто вкажіть параметр запиту timeout_ms з максимальним часом очікування зміни статусу замовлення на оплачено.

3.1.3.5. Більше навчальних посібників#

Щоб переглянути додаткові навчальні матеріали, ви можете переглянути цей сайт або перейти на https://docs.taler.net, щоб отримати найновішу документацію про сервіси Taler.