Mercado Pago 統合ガイド

このスキルは、Node.js/TypeScript アプリケーション、特にチャットコマース（WhatsApp/Instagram）とマルチテナント SaaS プラットフォームへの Mercado Pago 統合に必要なすべての機能を提供します。

クイック判定：どのチェックアウトを選ぶか

チェックアウト	最適な用途	実装難易度	チャット対応か
Checkout Pro	支払いリンク、チャットコマース、迅速なセットアップ	低	はい - init_point URL を送信
Checkout Bricks	サイトに埋め込む UI コンポーネント	中	いいえ - Web ページが必要
Checkout API	フルカスタムチェックアウト、最大限の制御	高	いいえ - フロントエンドが必要

チャットベースの販売（WhatsApp/Instagram ボット）では、常に Checkout Pro を使用してください。サーバー側でプリファレンスを作成し、init_point URL を抽出して顧客に送信します。

Node.js SDK セットアップ

npm install mercadopago
# v2.12.0 — TypeScript ネイティブ、クラスベース API

import { MercadoPagoConfig, Preference, Payment } from 'mercadopago';

const client = new MercadoPagoConfig({
  accessToken: '<ACCESS_TOKEN>',
  options: { timeout: 5000 }
});

利用可能な SDK クラス：MercadoPagoConfig（クライアント）、Preference、Payment、Order、Customer、CustomerCard、CardToken、OAuth、MerchantOrder、PaymentRefund、PaymentMethod、PreApproval、PreApprovalPlan、Invoice、IdentificationType、Point、User。

支払いリンクの作成（Checkout Pro）

const preference = new Preference(client);
const result = await preference.create({
  body: {
    items: [{
      id: 'product-123',
      title: 'Blue T-Shirt',
      quantity: 1,
      unit_price: 2500.00,
      currency_id: 'UYU' // または ARS、BRL、MXN、COP、CLP、PEN
    }],
    external_reference: 'your-order-id',
    notification_url: 'https://yoursite.com/webhooks/mp?source_news=webhooks',
    back_urls: {
      success: 'https://yoursite.com/payment/success',
      failure: 'https://yoursite.com/payment/failure',
      pending: 'https://yoursite.com/payment/pending'
    },
    auto_return: 'approved',
    expires: true,
    date_of_expiration: '2026-03-18T23:59:59.000-03:00',
    marketplace_fee: 250.00, // プラットフォーム手数料（マーケットプレイスモデル）
    binary_mode: false,      // false で pending を許可（現金支払い方法を含む）
  }
});

const paymentLink = result.init_point;          // 本番環境
const sandboxLink = result.sandbox_init_point;  // テスト環境

レスポンスの重要フィールド：id、init_point、sandbox_init_point、collector_id、external_reference。

ウェブフック処理

ウェブフックは支払いステータスの変更を通知します。ペイロードには data.id（支払い ID）のみが含まれます。ウェブフックを受け取った後は、常に支払い詳細全体を取得してください。

HMAC-SHA256 署名検証

import crypto from 'crypto';

function verifyWebhookSignature(
  xSignature: string,   // x-signature ヘッダーから
  xRequestId: string,   // x-request-id ヘッダーから
  dataId: string,       // クエリパラメータ data.id から
  secret: string        // MP ダッシュボードのウェブフックシークレット
): boolean {
  const parts = xSignature.split(',');
  let ts = '', hash = '';
  for (const part of parts) {
    const [key, value] = part.split('=').map(s => s.trim());
    if (key === 'ts') ts = value;
    if (key === 'v1') hash = value;
  }
  const manifest = `id:${dataId};request-id:${xRequestId};ts:${ts};`;
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(manifest);
  const calculated = hmac.digest('hex');
  return crypto.timingSafeEqual(Buffer.from(calculated), Buffer.from(hash));
}

ウェブフックのベストプラクティス

• HTTP 200 を即座に返し、非同期で処理する
• べき等性を実装する — MP が重複した通知を送る場合がある
• ペイロードの id は通知 ID です。支払い ID は data.id です
• ウェブフック後は常に Payment.get({ id }) で支払い詳細全体を取得する
• ウェブフック形式のみを取得するため notification_url に ?source_news=webhooks を追加する（レガシー IPN を除外）
• ウェブフック URL は HTTPS で公開アクセス可能である必要があります

支払いステータスのライフサイクル

created -> pending/in_process -> approved（完了）
                              -> rejected（完了）
                              -> cancelled（完了）
         -> authorized -> captured -> approved（認可＋キャプチャフロー）

主要なステータス：pending、approved、in_process、rejected、cancelled、refunded、charged_back。

OAuth マーケットプレイスモデル（マルチテナント）

SaaS プラットフォームで複数のマーチャントを接続し、各自が MP アカウントを持つ場合：

1. 認可 URL を生成

https://auth.mercadopago.com/authorization
  ?client_id=APP_ID
  &response_type=code
  &platform_id=mp
  &state=RANDOM_CSRF_TOKEN
  &redirect_uri=https://yoursite.com/connect/mp/callback

2. コードをトークンと交換（コードは 10 分で失効します！）

const response = await fetch('https://api.mercadopago.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: process.env.MP_CLIENT_ID,
    client_secret: process.env.MP_CLIENT_SECRET,
    code: authorizationCode,
    grant_type: 'authorization_code',
    redirect_uri: process.env.MP_REDIRECT_URI,
    test_token: false // サンドボックスの場合は true
  })
});
// 返却：access_token（180 日）、refresh_token、user_id、public_key

3. 失効前に更新

const response = await fetch('https://api.mercadopago.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: process.env.MP_CLIENT_ID,
    client_secret: process.env.MP_CLIENT_SECRET,
    grant_type: 'refresh_token',
    refresh_token: storedRefreshToken
  })
});

マーケットプレイス手数料

• Checkout Pro：プリファレンスの marketplace_fee — 売り手から差し引かれ、プラットフォームに送付
• Checkout API：支払いの application_fee
• 手数料は現地通貨で、売り手の売掛金から差し引かれます（買い手の合計には追加されません）

MCP サーバー

Mercado Pago を使用した AI 支援開発のための 3 つの MCP サーバーオプションがあります。完全なセットアップの詳細は references/mcp-servers.md を読んでください。

公式（リモート — 開発向け推奨）

{
  "mcpServers": {
    "mercadopago": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.mercadopago.com/mcp",
               "--header", "Authorization:Bearer <ACCESS_TOKEN>"],
    }
  }
}

ツール：search-documentation（自然言語で公式 MP ドキュメントを検索）。

コミュニティ（ローカル — 27+ 支払いツール）

{
  "mcpServers": {
    "mercado-pago": {
      "command": "npx",
      "args": ["mercado-pago-mcp"],
      "env": {
        "MERCADOPAGO_ACCESS_TOKEN": "YOUR_TOKEN",
        "MERCADOPAGO_ENVIRONMENT": "sandbox"
      }
    }
  }
}

ツール：create_payment、create_payment_link、search_payments、get_payment、refund_payment、create_subscription、create_customer、batch_create_payments、monitor_payment、analyze_fraud、export_to_accounting、simulate_webhook など。

よくある落とし穴

• external_reference：常に設定する — MP 支払いと注文を相関させるための唯一の信頼できる方法
• プリファレンスの失効：チャットリンクに対して expires: true + date_of_expiration を設定し、古い支払いを防止する
• サンドボックス：テスト認証情報で sandbox_init_point（init_point ではなく）を使用；MP ダッシュボードからテスト買い手/売り手アカウントを作成
• binary_mode: true：approved/rejected のみ（pending なし） — 現金支払い方法を除外
• 通貨：常に数値（例：75.76）、文字列ではない
• レート制限：プリファレンスの場合は約 100 req/s；HTTP 429 → エクスポーネンシャルバックオフ
• 国別認可 URL：AR：auth.mercadopago.com.ar、BR：auth.mercadopago.com.br など。API ベースは共通：api.mercadopago.com

国別支払い方法

国	通貨	主要方法
アルゼンチン（MLA）	ARS	カード、Rapipago、Pago Facil、MP Wallet
ブラジル（MLB）	BRL	カード、Pix、Boleto、MP Wallet
メキシコ（MLM）	MXN	カード、OXXO、SPEI
コロンビア（MCO）	COP	カード、PSE、Efecty、Baloto
チリ（MLC）	CLP	カード、Servipag、Webpay
ペルー（MPE）	PEN	カード、PagoEfectivo
ウルグアイ（MLU）	UYU	カード、Abitab、RedPagos

詳細リファレンス

データベーススキーマ、マルチテナントプリファレンス作成、支払いステータスの詳細、拒否理由コード、完全なウェブフックトピックリストを含む詳細なパターンについては、references/api-patterns.md を読んでください。

MCP サーバーのセットアップ、トラブルシューティング、ツールリストについては、references/mcp-servers.md を読んでください。

公式ドキュメントリンク

• Checkout Pro
• Checkout Bricks
• Checkout API
• ウェブフック
• OAuth / 認証情報
• Node SDK
• API リファレンス
• MCP サーバードキュメント