mcp-safrapay

@codespar/mcp-safrapay

Banco Safra のアクワイアラーである Safrapay 向けの MCP サーバーです。中規模から大規模のブラジル企業やプライベートバンキングの顧客に重点を置いた、B2B バンキングとの融合サービスです。

Safrapay の API は、Aditum の決済プラットフォーム上で運用されています（ドキュメントは safrapay-docs.aditum.com.br にあります）。ゲートウェイ、ポータル、照合、Webhook の各プロダクトは、個別のベースホストに分かれています。

ステータス：0.1.0-alpha.1。 ここに記載されているエンドポイントのパスは、Aditum がホストする Safrapay の開発者向けドキュメント（一般公開されています）をもとにしています。認証フロー（ゲートウェイでは BCRYPT + CNPJ、その後は JWT Bearer）はベストエフォートです。BCRYPT のハッシュ入力形式は公開ドキュメントで完全には仕様化されておらず、最終確認にはサンドボックスアカウントが必要になる可能性が非常に高いです。ライブのサンドボックス加盟店で検証するまでは、すべてのツールを足場として扱ってください。

ツール（22）

ツール	目的
authorize_payment	Safrapay でクレジットカード決済を承認します。
capture_payment	以前に承認された（事前承認済みの）決済をキャプチャします。
cancel_payment	承認済みで未キャプチャの決済をキャンセル（無効化）します。
refund_payment	キャプチャ済みの決済を返金します。
create_pix	Pix 請求を作成します。
create_boleto	boleto 請求を作成します。
get_payment	Safrapay の chargeId を指定して請求を取得します。
tokenize_card	PCI に準拠した安全な再利用のため、カードをトークン化します。
create_split_rule	既存の請求に対する分配ルールを設定します。
get_statement	電子明細（extrato）を取得します。
list_transactions	任意のフィルターを指定して請求を一覧表示します。
delete_card_token	保存済みのカードトークンを無効化します。
search_by_merchant_order	加盟店側の注文識別子（作成時に指定した order_id）で請求を検索します。
query_chargeback	請求のチャージバック（contestacao）の詳細（理由コード、アクワイアラーの期限、異議申し立て額、証拠など）を取得します。
query_installments	指定した金額の分割払いプランをシミュレーションします。
authenticate_3ds	authorize_payment の前に、3-D Secure 認証を開始します。
create_recurrence	継続課金のサブスクリプションを作成します。
get_recurrence	ID を指定して継続課金を取得します。スケジュール、次回請求日、請求履歴、ステータスを確認できます。
cancel_recurrence	有効な継続課金をキャンセルします。
get_settlement_report	照合ホストから入金（liquidacao）レポートを取得します。
create_payment_link	ホスト型チェックアウトの決済リンクを作成します。
register_webhook	Safrapay の Webhook プロダクトに Webhook サブスクリプションを一括登録します。

インストール

npm install @codespar/mcp-safrapay@alpha

環境

SAFRAPAY_CLIENT_ID="..."      # Merchant CNPJ (sent as merchantCredential)
SAFRAPAY_CLIENT_SECRET="..."  # MerchantToken (used to compute BCRYPT)
SAFRAPAY_MERCHANT_ID="..."    # Safrapay merchant id (body field where required)
SAFRAPAY_ENV="sandbox"        # 'sandbox' (default) or 'production'

ベース URL

Safrapay の API は、別々のドメインでホストされる4つのプロダクトに分かれています。

プロダクト	サンドボックス	本番環境
ゲートウェイ（決済）	https://payment-dev.aditum.com.br	https://payment.aditum.com.br
ポータル（管理）	https://portal-dev.aditum.com.br	https://portal-api.aditum.com.br
照合	https://reconciliation-dev.aditum.com.br	https://reconciliation-api.aditum.com.br
Webhook	https://webhook-dev.aditum.com.br	https://webhook.aditum.com.br

認証

ゲートウェイでは、次の2段階の初期認証を行います。

1. ヘッダー Authorization: <BCRYPT(CNPJ+MerchantToken)> と merchantCredential: <CNPJ> を付けて POST {gateway}/v2/merchant/auth を呼び出し、JWT アクセストークンと交換します。
2. 以降のリクエストでは Authorization: Bearer <jwt> を送信します。

サーバーは JWT を有効期限の60秒前までメモリにキャッシュします。BCRYPT 入力値の連結方法は、入手可能な情報に基づく推測です。サンドボックスアカウントを入手したら、改良してください。

実行

# stdio (default)
npx @codespar/mcp-safrapay

# HTTP
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-safrapay

エンドポイント一覧（ツールで使用）

ツール	メソッド	パス（特記がない限り、ゲートウェイ配下）
authorize_payment	POST	/v2/charge/authorization または /v2/charge/preauthorization
capture_payment	PUT	/v2/charge/capture/{chargeId}
cancel_payment	PUT	/v2/charge/cancelation/{chargeId}
refund_payment	PUT	/v2/charge/cancelation/{chargeId}（一部金額）
create_pix	POST	/v2/charge/pix
create_boleto	POST	/v2/charge/boleto
get_payment	GET	/v2/charge/{chargeId}
tokenize_card	POST	/v2/card（または /v2/temporary/card）
create_split_rule	PUT	/v2/charge/split/{chargeId}
get_statement	GET	/v2/Account/Movement/Extract
list_transactions	GET	/v2/charges
register_webhook	POST	{webhook}/v1/webhook/bulk

エンタープライズ

エージェントによる決済にガバナンス、予算上限、監査証跡が必要ですか？CodeSpar Enterprise は、これらの MCP サーバーにポリシーエンジン、決済ルーティング、コンプライアンステンプレートを追加します。

ライセンス

MIT