integrate-midtrans-payments

Midtrans 決済の統合

運用ルール

これは汎用的な API 接続ではなく、決済システムの統合として扱ってください。コードを変更する前に、加盟店のチェックアウトアーキテクチャ、決済商品、永続化モデル、コールバック経路、認証／セッション境界、環境管理、デプロイ先、テストハーネスを把握してください。

Midtrans の商品を推奨したり、コードを書いたりする前に、加盟店の準備状況に関する事前確認を完了してください。確認対象は、アカウントの状態、サンドボックス認証情報、有効な決済方法、想定される顧客フロー、ダッシュボードのコールバック URL、加盟店が求める証明レベルです。これらの情報が不足しており、プロジェクトからも推測できない場合は、暗黙に仮定せず、作業を中断して情報を求めてください。

毎回、最新の Midtrans ドキュメントを確認してください。まず https://docs.midtrans.com/llms.txt を検索し、次に実装対象の決済方法の製品ページを開いてください。llms.txt には各ページの .md 版へのリンクがあるため、HTML ではなくそちらを取得してください。

優先順位：エンドポイント、パラメーター、フィールド名、製品の提供状況については、最新の docs.midtrans.com の内容がこのスキルより優先されます。統合の規律（状態モデル、冪等性、署名の適切な扱い、検証）については、このスキルが優先されます。スキルのバージョンは 0.3.2 で、2026-06-25 に docs.midtrans.com に照らして検証されています。最新のドキュメントページがこのスキルと矛盾する場合は、ドキュメントに従い、加盟店に https://github.com/veritrans/midtrans-agent-skills/issues で相違点を報告するよう依頼してください。

ワークフロー

1. 加盟店の準備状況に関する事前確認を実施する

   • 製品を選択したりコードを書いたりする前に、merchant-readiness-preflight.md を完了してください。
   • 環境変数、デプロイ設定、運用手順書、テスト、プロバイダーのコード、仕様から推測し、不足している阻害要因についてのみ質問してください。
   • 利用できない決済方法は設定で無効化し、ダッシュボードまたは加盟店側で必要な対応を明示してください。

2. 統合を分類する

   • 加盟店が求めるものが、ホスト型チェックアウト、カスタム UI、継続課金／トークン化決済、マーケットプレイス／パートナー向けの動作、またはそのハイブリッドのどれかを特定してください。
   • コードを書く前に、依頼された各決済方法を、意図する Midtrans 製品に対応付けてください。
   • Snap、Core API、BI-SNAP のリクエスト形式、認証ヘッダー、コールバックの意味、ステータスオブジェクトを混在させないでください。
   • 加盟店のニーズが不明確な場合は、merchant-decision-tree.md を読み、必要最小限の確認事項を質問してください。

3. プロジェクトを調査する（必須の前提条件）

   • 製品の推奨、コードの作成、設定の編集を行う前に、project-adaptation.md を完了してください。
   • リポジトリの指示、環境変数の例、決済関連ドキュメント、チェックアウト／注文／決済のコード、データベーススキーマ、テスト、デプロイ設定を確認してください。
   • 既存の HTTP、ドメイン、プロバイダークライアント、永続化、UI、運用、ログの境界を把握し、アーキテクチャの変更を依頼されていない限り、それらを維持してください。
   • プロジェクトを調査できない場合（アクセス不可、リポジトリなし、新規構築など）は、その旨を明示して、加盟店が対象の技術スタックを確認するまで作業を中断してください。汎用的な回答を作り上げないでください。

4. 決済の状態モデルを設計する

   • チェックアウトを、決済方法の選択、決済の作成、決済待ち、支払い済み、失敗／キャンセル、期限切れ、返金済みという明示的な状態で表現してください。
   • プロバイダーを呼び出す前に、注文を creating_payment（または同等の状態）へ遷移させてください。そうすることで、プロバイダーの呼び出しが失敗しても、注文が未特定の状態のまま残ることを防げます。
   • リフレッシュ後も必要なプロバイダーデータを永続化してください。対象は、加盟店注文 ID、プロバイダー参照情報、決済方法、手順、リダイレクト／QR／VA データ、有効期限、最新のプロバイダーステータス、安全な生メタデータです。
   • コールバックを冪等かつ単調に処理してください。遅れて届いた pending または cancelled のコールバックによって、支払い済み／履行済み／返金済みの状態が上書きされないようにしてください。

5. プロバイダークライアントをサーバー側で構築する

   • マーチャントのスタックに適した公式 Midtrans ライブラリがある場合は、それを優先します。薄いラッパーを使う場合でも、環境変数の接続、リトライ、ログ記録、決済状態の管理を担います。
   • Midtrans のキー、署名、アクセストークン、顧客認可トークン、プロバイダーペイロードの署名はバックエンドで管理します。
   • Snap/Core API では、サーバーキーをユーザー名、空のパスワードとして Basic Auth を使用します。
   • BI-SNAP では、アクセストークン、トランザクション、通知の署名を分けて管理します。
   • 実際に送信するリクエスト本文のバイト列／文字列に署名します。
   • 製品固有のパターンと注意点については、midtrans-runtime-patterns.md を参照してください。

6. コールバックとステータス復旧を接続する

   • マーチャントダッシュボードには、インターネットからアクセス可能な HTTPS コールバック URL を設定します。
   • 注文を更新する前に、通知が本物であることを検証します。
   • ブラウザーのコールバックやユーザー向け決済結果は、フロントエンドのコールバックデータを信頼せず、バックエンドでステータスを照会して検証します。
   • コールバックを安全に受け付けた後、または後で照合するために意図的に保存した後にのみ、2xx を返します。

7. 計測と検証を行う

   • 決済の作成、プロバイダーの応答、コールバック、ステータスのポーリング、アカウント連携、キャンセル、返金、照合について、構造化ログを追加します。
   • 明示的に許可リストに登録されていない限り、シークレット、署名、認可ヘッダー、トークン、顧客の個人情報、プロバイダーのペイロード全体をマスキングします。
   • ステータスマッピング、署名の生成／検証、冪等なコールバック処理、有効期限切れの決済、無効化された決済方法、返金フロー、環境変数／デプロイ環境の不整合を網羅します。
   • verification-playbook.md を参照してください。
   • ユーザーがサンドボックスでの連携の証明、Webhook の再送、ステータスのポーリング、スモークテストの実行、またはサンドボックスの動作の診断を求めた場合は、sandbox-interaction-helper.md を参照してください。

8. エージェント間で利用できる形式の出力を準備する

   • 学んだ内容をスキルとしてパッケージ化するよう求められた場合は、SKILL.md を簡潔に保ち、製品の詳細は参照資料に移します。
   • 対象エージェントで追加の項目が必要な場合を除き、標準のフロントマター項目のみを使用します。
   • Claude、Codex、Copilot、Cursor、OpenCode、およびネイティブのスキルサポートを備えていないツールについては、agent-portability.md を参照してください。

Pathway References

加盟店のリクエストに関連するリファレンスのみを読み込んでください。

加盟店のリクエストまたは症状	読むファイル
Midtrans の新規実装、移行、検証に関するリクエスト全般	merchant-readiness-preflight.md および project-adaptation.md
Snap、Core API、BI-SNAP、Payment Link、またはハイブリッドのどれを使うべきか判断できない場合	merchant-decision-tree.md
Snap のみを使うホスト型チェックアウト、Snap ポップアップ／リダイレクト／埋め込み、Snap のウェブフックまたはステータスの不具合	snap-checkout.md
モバイルアプリ／WebView／ディープリンク	mobile-sdk.md
BI-SNAP QRIS、VA、単発の Direct Debit、署名、アクセストークン、通知ディスパッチャー	bisnap-core.md
GoPay の連携、トークン化ウォレット、GoPayLater、Binding Inquiry、アカウントの連携解除	gopay-tokenization.md
API またはダッシュボード経由の Payment Link、請求書／チャットでの代金回収、ソーシャルコマース、ノーコードでのリンク共有	payment-links.md
サブスクリプション API、カードの継続課金、保存済みトークンによる継続課金、継続課金通知のルーティング	subscriptions.md
従来の Core API によるカード／3DS／ワンクリック／分割払い、OTC（Alfamart／Indomaret）、レガシー VA	core-api-classic.md
上記で扱われていない、複数のプロダクトにまたがる実行時のパターンと注意点	midtrans-runtime-patterns.md および最新のドキュメント
返金の実行（全額または一部）、refund_key／partnerRefundNo の冪等性、BI-SNAP の返金、返金ウェブフックの処理	refund-operations.md
サンドボックスから本番環境への切り替え、コールバック、ログ、シークレット、スモークテスト、本番稼働の準備	operations-and-go-live.md
サンドボックスでの操作、スモークテスト、ウェブフックの再生、ステータスのポーリング、BI-SNAP 署名のドライラン、認証情報を安全に扱うテストコマンド	sandbox-interaction-helper.md および scripts/README.md
このスキルの改善、またはエージェントが正しく従っているかの確認	evaluation-prompts.md および evaluations.json

重要な組み合わせルール

• Snap の gross_amount：Snap トークンを作成するときは整数値、通知シグネチャを検証するときはプロバイダーから受け取った文字列をそのまま使います。金額を再フォーマットしてハッシュ化することは、Snap のシグネチャに関する最もよくあるバグです。
• BI-SNAP のシグネチャ：互いに独立した 3 つのヘルパーを使用します。アクセストークン用（非対称 RSA-SHA256）、トランザクション用（method:path:accessToken:bodyHashHex:timestamp に対する HMAC-SHA512）、通知用（Midtrans の公開鍵を使い、POST:path:bodyHashHex:timestamp を検証）。この 3 つでヘルパーを共用しないでください。
• GoPay のフロー：GoPay Direct Debit の単発決済、トークン化 GoPay ウォレット決済、GoPayLater、アカウントの連携、連携解除は、それぞれ異なる 5 種類のリクエスト形式です。トークン化決済には、Authorization-Customer: Bearer <customer_authorization_token> ヘッダーも必要です。このヘッダーは単発決済では送信しません。
• シームレスデータの署名（GoPay 連携）：現行ドキュメントでシームレス署名が必要な場合は、RSA-SHA256 で署名する前にデータを encodeURIComponent(...) でラップします。未加工の文字列に署名すると、サンドボックスではエラーが通知されずに失敗します。
• 返金の冪等性：返金リクエストのたびに refund_key（Snap/Core/Payment Link）または partnerRefundNo（BI-SNAP）を渡します。冪等性キーを付けずに返金を再試行すると、返金が二重に実行されます。
• サブスクリプションの管理元：顧客のサブスクリプションには、Midtrans 管理の Subscription API または加盟店主導の定期課金のどちらかを選びます。両方を実行すると、スケジュールされた課金が重複します。
• 定期課金の通知：定期課金では、通常の Payment Notification URL ではなく、ダッシュボードの Recurring Notification URL が使用される場合があります。定期課金の試行は単発決済とは分けてルーティングし、照合してください。

出力時の要件

ユーザーに回答する際は、次の内容を明記してください。

• 検出した Midtrans の製品区分と、その理由
• 加盟店の準備状況について、確認済みの事実、推定した事実、不足している情報
• プロジェクト固有のファイルと確認した境界
• 加盟店またはダッシュボードでの確認が必要な前提
• テストを含む実装または修正の計画
• 完了した検証と、サンドボックス／本番環境で残っているスモークテスト

実装時は、変更を小さくテスト可能な範囲に保ち、対象プロジェクトの既存の決済アーキテクチャとの互換性を維持してください。