Mercado Pago の SMS コードをテスト実行に取り込む

Mercado Pago の電話番号ステップで、チームは何に困っているのか？

Mercado Libre が提供する決済・デジタルウォレットの Mercado Pago は、ラテンアメリカの日常の商取引に定着しています。多くの金融アプリと同様に、アカウントは電話番号に紐づきます。登録時に SMS コードで番号を確認し、新しい端末でサインインしたりアクセスを回復したりするときに、新しいコードを求められることもあります。Mercado Pago を軸に開発するチーム、たとえばチェックアウトを連携するマーチャント、クライアントの出品者アカウントを運用するエージェンシー、決済で Mercado Pago を提供するマーケットプレイスをテストする QA エンジニアにとって、この SMS ステップはやっかいな部分になりがちです。スタッフが業務アカウントに私用の電話番号を登録したり、必要な SIM を持つ唯一の担当者がオフラインのためにテストケースが止まったりします。

OTP Route はこのステップを、ツールで扱えるものに変えます。必要な市場の番号をオンデマンドで取得し、コードをシステムに届けます。これが、テストのための Mercado Pago SMS 認証の中核です。

Mercado Pago 認証コード API のフローはどう動くのか？

すべてのリクエストは、Developer コンソールで発行した Bearer キー（プレフィックス or_live_）で https://otproute.com/api/v1 に送ります。サービス ID は mercado_pago で、国 ID は対象市場の api_country の値です。たとえばブラジルは br、メキシコは mx です。

1. GET /api/v1/prices?country=br&service=mercado_pago は、その組み合わせの最新の料金と提供状況を返します。
2. POST /api/v1/activations に {"service": "mercado_pago", "country": "br"} を送ると、アクティベーション ID と番号が返ります。
3. 設定中またはテスト中のアカウントの電話番号ステップに、その番号を入力します。
4. activation.sms_received がエンドポイントに届いたとき、または GET /api/v1/activations/{id} のポーリングでコードを取得します。
5. 実行が早く終わる場合は、POST /api/v1/activations/{id}/cancel を呼び出します。

事前確認には GET /api/v1/balance を使います。アカウントごとにキー 10 個、Webhook エンドポイント 5 個、1 分あたり 300 リクエストが利用でき、そのほかの詳細はドキュメントにあります。

Webhook ハンドラーは Mercado Pago のコードをどう扱うべきか？

プッシュ配信なら、テストランナーがポーリングのループで空回りせずに済みます。すべてのイベントに X-OTPRoute-Signature: t=<unix>,v1=<hex> が付きます。エンドポイントのシークレットで <t>.<raw body> の HMAC-SHA256 を計算し、定数時間で比較して、古いタイムスタンプのリクエストは破棄してください。そのうえでハンドラーを冪等にします。再試行は起こりうるため、アクティベーション ID を保存し、同じイベントの 2 回目の配信は無視します。activation.expired と activation.cancelled も受け取れば、ランナーがスロットを解放し、そのテストを再実行対象としてマークできます。エンドポイントを公開したくない場合は、数秒おきにアクティベーションをポーリングしても、レート制限には十分収まります。より詳しいチェックリストはOTP Webhook の保護にあります。

Mercado Pago の番号はどの国のものを選ぶべきか？

mercado_pago サービスは OTP Route の 201 か国に掲載されていますが、有用な選択はほとんどの場合、アカウントが属する市場です。Mercado Pago が特に知られているのは、ブラジル、アルゼンチン、メキシコ、チリ、コロンビア、ウルグアイ、ペルーで、多くのテストケースはそこにあります。カタログはほかにも、エクアドル、ボリビア、パラグアイ、コスタリカ、パナマ、ドミニカ共和国、スペイン、ポルトガル、米国などに及びます。

誤った国の番号は検証に失敗したり、追加の確認を招いたりすることがあり、その市場の実際のユーザーがフローをどう体験するかも分かりません。テストケースに合わせてください。ブラジルのオンボーディングにはブラジルの番号、チリのオンボーディングにはチリの番号を使います。

代わりにダッシュボードでできることは？

開発者でなくても、コードなしで同じ結果が得られます。OTP Gateway を開き、サービスに Mercado Pago、国を選び、注文前に表示される料金を確認します。番号をアプリにコピーして SMS を要求すると、配信され次第、アクティベーションカードにコードが表示されます。番号は 20 分間保持され、何も届かなければ課金されません。金額は自動的にウォレットへ戻ります。

Mercado Pago のコードが届かないのはなぜか？

決済プラットフォームは電話番号に慎重で、Mercado Pago 向けの仮想番号は一部またはすべてのフローで拒否されることがあります。ルートも一日のなかで変わります。コードが表示されない場合は次のようにします。

• 20 分の有効時間が終わるまで待ちます。返金は自動です。
• 短い間隔でループして再注文するのは避けます。間隔をあけるか、時間をおいて再試行します。
• 同じ市場のルートが何度も期限切れになる場合は、別のルートを試します。
• 電話番号の欄に、アプリが想定する形式で番号が入力されているか確認します。

フローが仮想番号を一貫して拒否する場合は、その結果を受け入れ、そのアカウントには実際の回線を使ってください。より広い原因の切り分けはOTP 配信失敗を減らす方法で解説しています。

専用番号のほうが適しているのはどんなときか？

使い切りの番号は 1 回のコードに対応します。数か月後にあらためて新しいコードを求めるビジネスアカウントには、引き続き自分で管理できる番号が必要です。OTP Route の専用番号（Dedicated Numbers）は米国とカナダでその役割を果たし、月額 $1.95 からです。ダッシュボードと Webhook（number.sms_received）で SMS を受信でき、送信 SMS とブラウザー通話にも対応し、回線を解除するまでウォレットから更新されます。この 2 か国以外には、セルフサービスの長期回線はありません。提供の可否は現地の規則に左右されるため、[email protected] にメールでお問い合わせください。詳細は仮想番号をご覧ください。

Mercado Pago でこれらの番号を使うときのルールは？

Mercado Pago は実際のお金を動かすサービスであり、本人確認には正当な理由があります。OTP Route の電話番号はその確認の代わりにはならず、回避に使ってはいけません。実際の情報で本人確認を完了し、アカウントは実在の個人または事業者につき 1 つとし、OTP Route の利用規約（Acceptable Use Policy）に加えて Mercado Pago の規約も守ってください。このプラットフォームは、ご自身の製品のテストと正当なアカウントの運用のためのものであり、大量のアカウント開設やプロモーションの受け取りのためのものではありません。課金は、プリペイドの USD ウォレット（カードまたは USDT/USDC、入金ごとに PDF の請求書）による従量課金で、連携テスト用にシミュレートされたコードのサンドボックスをご依頼いただけます。Mercado Pago はその所有者の商標であり、OTP Route は提携していません。

よくある質問

ブラジルやメキシコの現地 SIM がなくても Mercado Pago の OTP を受信できますか？

はい。ご自身のアカウントのテストや運用であれば可能です。適切な国の mercado_pago の番号を注文し、ダッシュボード、API、Webhook でコードを読み取ります。

API での Mercado Pago のサービス ID は何ですか？

mercado_pago です。POST /api/v1/activations の本文で国 ID と組み合わせます。

Mercado Pago は仮想番号を受け付けますか？

常にではありません。一部のフローで拒否されることがあるため、20 分以内にコードが届かなければ全額が返金されます。

認証用の Mercado Pago の電話番号の料金はいくらですか？

1 コード $0.20 からです。正確な価格は国によって異なり、注文前に API とダッシュボードで確認できます。

来月ログインするとき、同じ使い切りの番号を使えますか？

いいえ。使い切りの番号は 1 回のコードしか受信しません。繰り返しサインインが必要なアカウントには、米国またはカナダの専用番号のほうが向いています。

CI パイプラインで、実際の課金なしに Mercado Pago のフローを試せますか？

はい。開発用アカウントでサンドボックスモードを依頼してください。同じエンドポイントでシミュレートされた番号とコードが返されます。

サービス名はそれぞれの所有者の商標です。OTP Route はこれらの企業と提携していません。番号は合法的にご利用いただき、各サービスの利用規約および当社の利用規定に従ってください。