Tworzenie zamówień

3.1.3. Tworzenie zamówień#

Ta strona zawiera całą dokumentację do samouczka wideo wyjaśniającego proste tworzenie zamówienia za pośrednictwem interfejsu API i sprawdzanie jego statusu.

3.1.3.1. Wideo#

3.1.3.2. Wymagania#

Wymagane dla tej serii samouczków:

  • Zaplecze handlowe Taler
    Jeśli potrzebujesz pomocy w korzystaniu z backendu sprzedawcy po raz pierwszy, możesz obejrzeć samouczek Taler merchant introduction.
  • Instancja portfela Taler
    Instrukcje konfiguracji są dostępne na stronie https://wallet.taler.net.
  • Oprogramowanie do zarządzania REST API lub odpowiednie umiejętności programistyczne
    W tej serii wideo będziemy korzystać z bezpłatnego oprogramowania Insomnia, dostępnego do pobrania na stronie https://insomnia.rest.

3.1.3.3. Powiadomienie o wersji demonstracyjnej backendu#

W tym samouczku można skorzystać z własnej usługi zaplecza sprzedawcy lub usługi demonstracyjnej online pod adresem https://backend.demo.taler.net/instances/sandbox/.

3.1.3.4. Więcej informacji na temat przetwarzania płatności przez sprzedawców#

  1. Tworzenie zamówienia płatności

Płatności w Taler opierają się na zamówieniu, które jest maszynowym opisem transakcji biznesowej, za którą ma zostać dokonana płatność. Przed zaakceptowaniem płatności Taler jako sprzedawca musisz utworzyć takie zamówienie.

Odbywa się to poprzez POST obiektu JSON do punktu końcowego API backendu /private/orders. Co najmniej następujące pola muszą być podane wewnątrz pola order:

  • amount: Kwota do zapłaty, jako ciąg znaków w formacie CURRENCY:DECIMAL_VALUE, na przykład EUR:10 dla 10 euro lub KUDOS:1.5 dla 1.5 KUDOS.

  • summary: Czytelne dla człowieka podsumowanie tego, czego dotyczy płatność. Podsumowanie powinno być na tyle krótkie, aby zmieściło się w tytule, ale nie ma sztywnego limitu.

  • fulfillment_url: Adres URL, który zostanie wyświetlony po zakończeniu płatności. W przypadku towarów cyfrowych powinna to być strona wyświetlająca zakupiony produkt. Po udanej płatności portfel automatycznie dołącza order_id jako parametr zapytania, a także ession_sig dla płatności związanych z sesją (omówione poniżej).

Zamówienia mogą mieć o wiele więcej pól, zobacz Format zamówienia Taler. Podczas wysyłania zamówienia można również określić dodatkowe szczegóły, takie jak nadpisanie czasu trwania zwrotu i instrukcje dotyczące zarządzania zapasami. Są one rzadko potrzebne i nie zostały omówione w tym samouczku; szczegółowe informacje można znaleźć w podręczniku referencyjnym.

Minimalny fragment Pythona do tworzenia zamówienia wyglądałby następująco:

>>> 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]>

Backend uzupełni niektóre szczegóły brakujące w zamówieniu, takie jak adres instancji sprzedawcy. Pełne szczegóły nazywane są warunkami umowy.

Informacja

Powyższe żądanie wyłącza użycie tokenów roszczeń poprzez ustawienie opcji create_token na false. Jeśli potrzebujesz tokenów roszczeń, musisz dostosować kod, aby skonstruować URI taler://pay/ podany poniżej, aby zawierał token roszczenia.

Po pomyślnym wysłaniu POST do /private/orders, zwrócony zostanie JSON z polem order_id z ciągiem znaków reprezentującym ID zamówienia. Jeśli otrzymasz również token roszczenia, sprawdź dokładnie, czy użyłeś żądania zgodnie z powyższym opisem.

Wraz z instancją sprzedawcy, identyfikator zamówienia jednoznacznie identyfikuje zamówienie w backendzie sprzedawcy. Korzystając z identyfikatora zamówienia, można trywialnie skonstruować odpowiedni identyfikator URI taler://pay/, który musi zostać dostarczony do portfela. Niech example.com będzie nazwą domeny, w której dostępne są publiczne punkty końcowe instancji. Identyfikator URI płatności Taler to po prostu taler://pay/example.com/$ORDER_ID/, gdzie $ORDER_ID należy zastąpić identyfikatorem zwróconego zamówienia.

Możesz umieścić identyfikator URI taler:// jako cel linku, aby otworzyć portfel Taler za pośrednictwem schematu taler:// lub umieścić go w kodzie QR. Jednak w przypadku sklepu internetowego najłatwiej jest po prostu przekierować przeglądarkę na stronę https://example.com/orders/$ORDER_ID. Ta strona uruchomi portfel Taler. Tutaj backend generuje odpowiednią logikę do uruchomienia portfela, obsługując różne rodzaje istniejących portfeli Taler. Zamiast ręcznie konstruować powyższy adres URL, można go również uzyskać, sprawdzając status płatności, jak opisano w następnej sekcji.

Podczas ręcznego konstruowania tego adresu URL należy podać token roszczenia (chyba że został wyłączony) i jeśli backend działa bez TLS, aby użyć taler+http:// (należy pamiętać, że ten ostatni jest obsługiwany tylko przez portfele działające w trybie debugowania).

Informacja

Trywialnym sposobem na uzyskanie poprawnego payment_redirect_url jest sprawdzenie statusu płatności (patrz poniżej). Jeśli więc nadal nie masz pewności, jak go skonstruować, możesz po prostu poprosić backend, aby zrobił to za Ciebie. Jednak w środowisku produkcyjnym prawdopodobnie powinieneś skonstruować go ręcznie i uniknąć dodatkowego żądania do backendu.

  1. Sprawdzanie statusu płatności i monitowanie o płatność

Biorąc pod uwagę identyfikator zamówienia, status płatności można sprawdzić za pomocą punktu końcowego /private/orders/$ORDER_ID. Jeśli płatność nie została jeszcze zrealizowana przez klienta, /private/orders/$ORDER_ID da frontendowi adres URL (pod nazwą payment_redirect_url), który uruchomi portfel klienta w celu wykonania płatności. Jest to w zasadzie adres URL https://example.com/orders/$ORDER_ID, który omówiliśmy powyżej.

>>> 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())

Jeśli pole order_status w odpowiedzi to paid, nie otrzymasz payment_redirect_url, a zamiast tego informacje o statusie płatności, w tym:

  • contract_terms: Pełne warunki zamówienia.

  • refunded: true, jeśli (ewentualnie częściowy) zwrot został przyznany za ten zakup.

  • refunded_amount: Kwota, która została zwrócona

Gdy frontend potwierdzi, że płatność się powiodła, zwykle musi uruchomić logikę biznesową dla sprzedawcy, aby wypełnić zobowiązania sprzedawcy wynikające z umowy.

Informacja

Nie ma potrzeby ciągłego odpytywania, aby zauważyć zmiany w statusie transakcji zamówienia. Punkty końcowe obsługują długie odpytywanie, wystarczy określić parametr zapytania timeout_ms z czasem oczekiwania na zmianę statusu zamówienia na opłacone.

3.1.3.5. Więcej samouczków#

Aby wyświetlić dodatkowe samouczki, możesz przejrzeć tę stronę lub udać się na https://docs.taler.net, aby uzyskać najnowszą dokumentację dotyczącą usług Taler.