API Pagou でのクレジットカード
まず、スキル pagou のルール（環境、バックエンド認証、セキュリティ、不確実な結果）を適用してください。このスキルはカードに関する判断のみを提供します。フィールドとペイロードは以下のページに記載されています。実装前に必ずお読みください。
実装前に読むべきドキュメント
- 支払い方法: クレジットカード
- カードのトークン化
- 請求の作成
- 請求の照会と一覧表示
- 冪等性と繰り返し
- 参照フロー: 顧客（支払い者）の作成、カードの作成、支払い者の管理、カードの管理
- フローで必要な場合: 承認された請求の売上確定、請求のキャンセル、請求の返金、再試行、請求の更新、チャージバック
- アカウントの有効化: 加盟店契約の申請
前提条件
アクティブなアカウント、承認済みのカード加盟店契約、カード手数料が設定されたプラン、有効な API キーが必要です。加盟店契約は API ではなく管理画面から申請します。アカウントが加盟店契約を結んでいない場合は、実装前にユーザーにその旨を伝えてください。
必須アーキテクチャ
- ブラウザ: 独自のチェックアウト画面でカードデータを収集し、請求に使用する API と同じ環境で Pagou のトークン化ライブラリを使ってトークンを生成します。ライブラリの公開鍵は
X-API-KEYではありません。 - ブラウザからバックエンドへ: トークン化された
cardオブジェクトと購入データのみを店舗サーバーに送信します。トークン化後は、フォームのフィールドや状態からカード番号と CVV を消去します。 - 加盟店バックエンド:
X-API-KEYを使用して API に請求を作成します。このキーがブラウザ側に露出することは決してありません。
完全なカード番号と CVV は API の契約範囲に含まれません。ログ、分析ツール、ブラウザストレージにカード番号、CVV、トークンを記録しないでください。Pagou のチェックアウトは既にトークン化を行っています。このアーキテクチャは独自のチェックアウトに適用されます。
判断ルール
-
金額は整数のセントで指定:
value: 5000は R$ 50,00 を表します。Pix や銀行振込の単位を流用しないでください。 -
次の2つのフローのうち、正確に1つを選択:
- 完全データ:
customerオブジェクトとcardオブジェクト（トークンを含む）。 - 参照: 同一支払い者の
customer_idとcard_id。両方とも認証されたアカウントに属する必要があります。このフローでは新しいトークンを生成しないでください。
フローを混在させたり、ペアの一方だけを送信したりしないでください。完全データフローでは、返された ID を保存して将来再利用できるようにします。
- 完全データ:
-
不正防止: 購入者の実際の IP アドレスを含む、ドキュメントに記載された要件に従ってください。例で使用されているサンプル IP を使用しないでください。
-
分割払い: カードブランドの制限を尊重し、カードの有効期限が切れていないことを確認してください。
-
statusによる金融結果の確認:201が承認を保証するわけではありません。authorized（承認）、captured（売上確定）、settled（決済完了）を区別してください。請求のunknown状態は、不確実な結果を伴う通信エラーとは異なります。 -
売上確定は必須ステップではない: 作成時に既に
capturedが返される場合があります。明示的な売上確定は、authorizedのままの請求に対して、かつそれが商取引上の意図である場合にのみ呼び出してください。タイムアウト解決のために売上確定を使用しないでください。 -
キャンセルと返金の区別: キャンセルは保留中の請求に適用されます。承認済み、売上確定済み、決済済みの請求には返金ルールが適用されます。現在の契約では返金は全額返金です。選択する前に状態を確認してください。
-
再試行 (
/retry): これは別の金融操作です。確認された失敗 (failed) の後でのみ、独自のキーを使用し、ドキュメントに記載された制限内で実行します。タイムアウトや不確実な結果を解決するために/retryを使用しないでください。 -
チャージバック: 紛争操作にはチャージバックの
idを使用します。紛争の状態は請求のcharged_back状態とは異なります。異議申し立てと受け入れは加盟店の判断です。要求があった場合のみ実装してください。 -
分割払い（Split）: スキル
pagou-splitに従ってください。カードの場合、請求はセントを使用しますが、Split の固定金額はレアル（R$）を使用します。
冪等性
- 商取引ごとに（支払い者登録、カード登録、請求作成、売上確定、返金、再試行）一意の
Idempotency-Keyを生成し、最初の送信前にリクエストとともに保存します。 - 同じ操作を繰り返すには、同じキー、メソッド、パス、および
card_tokenと split 配列を含むリクエストボディのバイトをそのまま維持します。JSON を再構築しないでください。 - 新しい購入には新しいキーが必要です。
customer_idとcard_idは再利用できます。 - ループ内で新しいキーを生成したり、タイムアウトを回避するために使用したりしないでください。
idempotency_key_conflict、idempotency_in_progress、idempotency_outcome_unknownコードはそれぞれ異なる処理が必要です。冪等性のドキュメントをお読みください。不確実な結果は照会によって調査する必要があり、新しい請求を作成してはいけません。
MCP ツール
Pagou の MCP はカード請求の読み取りのみを行います:
| ツール | 使用法 |
|---|---|
get_card_charge | ID で請求を照会 |
list_card_charges | ステータスと期間で一覧表示および照合 |
MCP はカード請求の作成、売上確定、キャンセル、返金、再試行を行わず、支払い者やカードの管理、チャージバックへの対応も行いません。作成はブラウザでのトークン化後に加盟店のバックエンドで行われます。エージェントから他の方法でカード請求を作成しようとしないでください。
Sandbox でのテスト
- Sandbox アカウントがカードの前提条件を満たしていることを確認します。
- トークン化のドキュメントに従って、Sandbox 環境でテストカード
4111 1111 1111 1111をトークン化します。 - アプリケーションのバックエンドから
https://api.pagou.cloudに対して、Sandbox キーと独自のIdempotency-Keyを使用して請求を作成します。Pix のシミュレーションルートはカードには適用されません。 - 返された
statusを確認し、同じ請求を照会します（get_card_chargeも使用できます）。 - 同じキーで同じリクエストを繰り返し、重複した請求が発生しないことを確認します。