請求書で支払いを受け取る

請求書は、Telegramユーザーに料金を請求するしくみです。APIで作成したリンクを支払者に送ります。支払いが成功すると、加盟店手数料を引いた金額がアプリの残高に反映されます。

支払いの流れ

1. 請求書を作成します。createInvoiceに資産と金額を渡します（法定通貨建てにもできます。下記を参照してください）。
2. **レスポンスのリンクを支払者に送ります。**開くと、アプリの支払い画面が表示されます。
3. 支払者が確定して、残高から支払います。 すぐに完了し、ネットワーク手数料はかかりません。 外部ウォレットからの入金が選べる場合、残高が足りない支払者はその方法を使えます。自動支払いには、期限内に十分な残高が反映され、送金・出金の制限がないことが必要です。入金だけでは、請求書の支払いが済んだことにはなりません。
4. **通知が届きます。**Webhook URLを設定していれば、支払い後にinvoice_paidイベントが送信待ちになります。手数料を引いた金額がアプリの残高に入ります。
5. **注文を処理します。**まずWebhookの署名を検証し、請求書が対象の注文と一致し、ステータスがpaidであることを確認してください。getInvoicesでも確認できます。追加のブロックチェーン承認を待つ必要はありません。

Webhookではなくポーリングにしたい場合は、getInvoicesが請求書と現在のステータスを返します。 速いのはWebhookで、ポーリングは代替の手段です。

法定通貨建ての価格

請求書の価格は、暗号資産で決めることも、法定通貨で決めて受け取れる資産を指定することもできます。 支払者は、持っている対応資産のどれかで支払い、支払い時点のレートで換算されます。 価格を法定通貨で管理している店舗には、こちらが向いています。

価格を固定して見せたい場合は、rate_lock_secondsで作成時の換算レートを一定の時間だけ固定できます。 支払者には固定された金額がそのまま表示され、その間のレート変動は加盟店側が引き受けます。 詳しくは請求書のリファレンスを確認してください。

swap_toを指定すると、届いた支払いを1つの資産に自動で交換できます。 交換を実行できない場合も、元の資産で支払いは成立します。is_swappedとswapped_*のフィールドを確認してください。

よく使う請求書のオプション

• description：支払い画面で支払者に表示されます。
• hidden_message：支払いが終わったあとだけ支払者に表示されます。 コード、キー、リンクなどを、別の連絡手段なしで渡せます。
• payload：自分で自由に決める文字列で、Webhookにそのまま返ってきます。 注文IDはここに入れてください。
• expires_in：期限です。これを過ぎると、請求書は支払えなくなります。
• paid_btn_name / paid_btn_url：支払い後に支払者に表示されるボタンです。 自分のボット、チャンネル、商品ページへ戻せます。
• open_amount：金額を固定せず、支払者が支払い時に入力します。 寄付やチップに向いた形です。

説明、支払い後のコンテンツ、ボタンは、内容が承認されるまで支払者に表示されない場合があります。作成直後から必ず表示されるとは限りません。

未払いの請求書は、deleteInvoiceでキャンセルできます。

返金

refundInvoiceは、実際に支払われた暗号資産、またはその一部を、アプリの残高から支払った相手に返します。 匿名で支払った相手にも、誰かを明かさずに返せます。 一部返金の累計は、実際に支払われた暗号資産の金額までで、請求書のrefunded_amountに記録されます。 法定通貨建ての請求書では、法定通貨の額面ではなくpaid_assetとpaid_amountを使います。自動交換をした場合も、元の支払い資産の残高を十分に用意する必要があります。 spend_idを渡しておくと、タイムアウトした再送で二重に返金せず、同じ結果を返します。 サービス手数料は返金されません。

⚠️ 注文を処理する前にWebhookの署名を検証する

Webhook URLには誰でもPOSTできます。 支払いを本物として扱う前に、TgPayCrypto-API-Signatureヘッダーを確かめてください。 生のリクエストボディに対するHMAC-SHA256で、鍵はメインAPIトークンのSHA-256です。 あわせてupdate_idで重複を排除し、再送で注文を二重に出荷しないようにしてください。