オーダーの作成

3.1.3. オーダーの作成#

このページには、APIを通した簡単な注文の作成とそのステータスのチェックを説明するビデオチュートリアルのすべてのドキュメントが含まれています。

3.1.3.1. ビデオ#

3.1.3.2. 必要条件#

このチュートリアルシリーズに必要：

  • Talerマーチャントバックエンド
    マーチャントバックエンドを初めて使用する際にヘルプが必要な場合は、 Taler merchant introduction チュートリアルをご覧ください。
  • Talerウォレットのインスタンス
    セットアップ方法はhttps://wallet.taler.net。
  • REST API管理ソフトウェアまたは関連プログラミングスキル
    このビデオシリーズでは、https://insomnia.rest からダウンロードできるフリーソフト「インソムニア」を使用します。

3.1.3.3. デモ・バックエンドのお知らせ#

このチュートリアルでは、ご自身のマーチャント・バックエンド・サービス、または https://backend.demo.taler.net/instances/sandbox/ のオンライン・デモンストレーション・サービスをご利用いただけます。

3.1.3.4. マーチャント決済処理に関するその他の注意事項#

  1. 支払い注文の作成

Talerでの支払いは、*オーダー*を中心に展開されます。これは、支払いが行われるビジネストランザクションの機械読み取り可能な説明です。マーチャントとしてTalerの支払いを受け入れる前に、そのようなオーダーを作成する必要があります。

これはバックエンドの /private/orders APIエンドポイントにJSONオブジェクトをPOSTすることで行います。少なくとも以下のフィールドを order フィールドの中に指定しなければならない：

  • 金額``amount``：例えば10ユーロなら EUR:10 、1.5クドスなら KUDOS:1.5 です。

  • 概要 summary：その支払いが何についてのものなのか、人間が読める要約。要約はタイトルに収まるような短さでなければならないが、特に厳しい制限はない。

  • fullfillment_url``：支払いが完了すると表示されるURL。デジタル商品の場合、購入した商品を表示するページである必要があります。支払いが完了すると、ウォレットは自動的に order_id をクエリパラメータとして追加します。

Talerオーダーフォーマット<#The-Taler-Order-Format>`__を参照してください。 注文をPOSTするとき、払い戻し期間のオーバーライドや在庫管理の指示のような追加詳細を指定することもできます。詳細は`リファレンスマニュアル<https://docs.taler.net/core/api-merchant.html>`_を参照してください。

注文を作成するための最小限の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 に設定することで、クレームトークンの使用を無効にしています。 クレームトークンが必要な場合は、以下に示す taler://pay/ URI を作成するコードを調整し、クレームトークンを含める必要があります。

private/orders``への POST 送信に成功すると、注文IDを表す文字列を含む order_id フィールドだけのJSONが返されます。クレームトークンも返される場合は、上記のようにリクエストを使用したかどうかを再確認してください。

マーチャントの インスタンス と共に、オーダー ID はマーチャントのバックエンド内でオーダーを一意に識別します。 オーダー ID を使用すると、ウォレットに提供する必要がある taler://pay/ URI を簡単に作成することができます。 インスタンスのパブリックエンドポイントに到達可能なドメイン名を example.com とする。ここで $ORDER_ID は、返された注文のIDに置き換える必要がある。

taler://スキーマを経由してTalerウォレットを開くリンクのターゲットとして``taler://`URI'を置くか、QRコードに置くことができます。 しかし、ウェブショップの場合、最も簡単な方法は、単純にブラウザを ``https://example.com/orders/$ORDER_ID` にリダイレクトすることである。 そのページがTalerウォレットをトリガーします。ここで、バックエンドはウォレットをトリガーする適切なロジックを生成し、存在する様々なタイプのTalerウォレットをサポートします。 上記のURLを手作業で構築する代わりに、次のセクションで説明するように、支払いステータスをチェックして取得することも可能です。

この URL を手動で作成する場合は、(無効化されていない限り)クレームトークンを指定し、** バックエンドが TLS なしで動作している場合は taler+http:// を使用するようにしてください(後者はデバッグモードで動作しているウォレットでのみサポートされていることに注意してください)。

注釈

正しい payment_redirect_url を取得する簡単な方法は、支払いのステータスをチェックすることです（下記参照）。そのため、どのように構築すればよいかわからない場合は、バックエンドに依頼することもできます。しかし、本番環境では、バックエンドへの余分なリクエストを避けるために、手動で作成したほうがよいでしょう。

  1. 支払い状況の確認と支払いの催促

注文IDが与えられれば、/private/orders/$ORDER_ID``エンドポイントを使用して支払いのステータスを確認することができる。顧客がまだ支払いを完了していない場合、/private/orders/$ORDER_ID`` はフロントエンドに（payment_redirect_url` という名前で）顧客のウォレットが支払いを実行するきっかけとなる URL を渡します。これは基本的に、上で説明した https://example.com/orders/$ORDER_ID URLです。

>>> 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``：注文の完全な契約条件。

  • refunded``: この購入に対して(おそらく部分的な)払い戻しが行われた場合は true となります。

  • 払い戻された金額 refunded_amount：返金された金額

フロントエンドは、支払いが成功したことを確認すると、通常、契約に基づく加盟店の義務を果たすために、加盟店のビジネスロジックをトリガーする必要がある。

注釈

注文のトランザクションステータスの変更に気づくために、クエリを実行し続ける必要はありません。 エンドポイントは長時間のポーリングをサポートしており、注文ステータスが paid に変更されるまでの最大待機時間を timeout_ms クエリパラメータに指定するだけです。

3.1.3.5. その他のチュートリアル#

その他のチュートリアルを見るには、このサイトを閲覧するか、https://docs.taler.net、Talerサービスに関する最新のドキュメントを入手することができます。