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

請求書は、Telegramユーザーに料金を請求するしくみです。APIで作成してリンクを支払者に送ると、支払者が確定した瞬間にアプリの残高に反映されます。

支払いの流れ

1. 請求書を作成します。createInvoiceに資産と金額を渡します（法定通貨建てにもできます。下記を参照してください）。
2. **レスポンスのリンクを支払者に送ります。**開くと、アプリの支払い画面が表示されます。
3. 支払者が確定して、残高から支払います。 すぐに完了し、ネットワーク手数料はかかりません。 残高が足りない支払者は、外部のウォレットから請求書に入金できます。 その送金が届くと自動で支払いが成立し、加盟店から見えるものは変わりません。
4. 通知が届きます。invoice_paidのWebhookが発火し、金額がアプリの残高に入ります。
5. **注文を処理します。**ほかに待つものはありません。その時点で支払いは確定しています。

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

法定通貨建ての価格

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

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

swap_toを指定すると、届いた支払いを1つの資産に自動で交換できます。 自分で交換を実行せずに、残高をステーブルコインでまとめておきたいときに便利です。

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

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

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

返金

refundInvoiceは、支払い済みの請求書の額面、またはその一部を、アプリの残高から支払った相手に返します。 匿名で支払った相手にも、誰かを明かさずに返せます。 一部返金は額面に達するまで積み上がり、請求書のrefunded_amountに記録されます。 spend_idを渡しておくと、タイムアウトした再送で二重に返金せず、同じ結果を返します。 サービス手数料は返金されません。

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

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