Claude Media
Claude CodeのAirwallexプラグインでAPI連携のコードを生成する
Claude CodeMCPClaude連携チュートリアル

Claude CodeのAirwallexプラグインでAPI連携のコードを生成する

Airwallex Dev(airwallex-dev)は決済UIや課金のコードを生成する6つのスキルとサンドボックスMCPのプラグインです。導入手順、スキルの選び分け、生成後の確認までを説明します。

読了目安 約15分

Airwallex Dev(インストールIDは airwallex-dev)は、Airwallexの決済UI・サブスクリプション課金・コネクテッドアカウントのKYCを、自分のプロジェクトに組み込むコードをエージェントに書かせるためのプラグインです。中身は、6つのスキルとサンドボックス向けのMCPサーバー設定です。

導入は2つのコマンドで済みます。迷いやすいのは入れた後で、同じマーケットプレイスに別のプラグイン(airwallex-agentos)があること、スキルごとに対象の決済方式が違うことです。この記事では、導入からスキルの選び分け、生成されたコードを本番に出す前の確認までを順に説明します。

airwallex-devが生成するもの

Claude Marketplaceのプラグインページでは、このプラグインは「Anthropic verified」の表示付きで、決済APIの組み込み(スキャフォールド、設定、配線)を行うコード生成ワークフローとして紹介されています。リポジトリのREADMEによれば、スキルが扱うのは会話ではなくプロジェクトのコードです。

6つのスキルのうち5つはコードを直接生成します。残る1つの airwallex-ai-provider-card-mit だけは、コードでなく実装計画のドキュメントを出力します。

スキル領域生成物の中心
airwallex-hpp領域決済生成物の中心Airwallex側に遷移するHosted Payment Page
airwallex-dropin領域決済生成物の中心複数の決済方法を載せる埋め込みUI
airwallex-split-card領域決済生成物の中心カード番号・有効期限・CVCを分けた入力欄
airwallex-billing-checkout領域課金生成物の中心サブスクリプション・単発払い・カード保存のチェックアウト
airwallex-kyc領域コネクテッドアカウント生成物の中心埋め込みまたはホスト型のKYCオンボーディング
airwallex-ai-provider-card-mit領域決済生成物の中心カード保存型の事業者起点課金(MIT)の実装計画

各スキルは SKILL.md に分岐の指示を持ち、SDKのスニペットやAPIスキーマは references/ 以下に分けて置いています。エージェントは該当シナリオに必要な参照ファイルだけを読む作りです。導入後のコンテキスト消費はclaude plugin detailsで測れます。

Claude Codeへの導入手順

Airwallex自身のマーケットプレイスを登録してから、プラグインを入れます。

claude plugin marketplace add https://github.com/airwallex/airwallex-marketplace
claude plugin install airwallex-dev@airwallex-marketplace

起動中のセッションで入れた場合、プラグインは次の起動時に読み込まれます。開いたままのセッションに反映するには /reload-plugins を実行します。

マーケットプレイスには airwallex-agentos(請求書の作成、受取人の登録、カード発行、資金状況の集計といった業務用スキル)と、廃止済みの旧 airwallex も載っています。コードを書かせたいだけなら、入れるのは airwallex-dev だけです。旧 airwallex は airwallex-agentos に改名されたもので、READMEは0.1.x系からの移行時にスキル呼び出しを /airwallex:… から /airwallex-agentos:… に直すよう案内しています。

スキルの呼び出し方

インストールしたスキルはプラグイン名が前に付きます。

/airwallex-dev:airwallex-hpp

スキルの description には、HPP、Drop-in、billing_checkouts といった語に反応する記述があります。語を含めて頼む使い方を想定した記述です。対象の取り違えを避けたいときは、明示的に呼ぶほうが確実です。

MCPが自動で入る範囲

READMEによると、Claude Code・Cursor・Codexのプラグインとして入れた場合はMCPコネクターも一緒に入ります。プラグインに同梱された .mcp.json は、HTTP型のサーバー airwallex-dev を mcp.sandbox.airwallex.com のdeveloperエンドポイントに向けています。名前のとおりサンドボックス向けの接続先です。

npx skills add airwallex/airwallex-marketplace で入れた場合はスキルだけが入り、MCPは入りません。MCPが要るなら自分のクライアント設定に足す必要があります。

MCPは多くのスキルで任意です。スキルの参照ファイルで足りない質問が出たときに、最新のAPIドキュメント検索とサンドボックスAPIの呼び出しに使う、という位置づけです。例外が airwallex-ai-provider-card-mit で、こちらはAPIのフィールドとSDKの形をMCPで検証してから書く作りのため、MCPが必須になります。

MCPの接続でエラーが出たときはstored credentialsのエラーの対処が参考になります。

決済UIはどのスキルで作るか

決済UIの3スキルは、サイトのどこまでをAirwallexに任せるかで選びます。スキルのリファレンスにある比較は次のとおりです。

観点HPPDrop-inSplit Card
組み込みの手間HPP最小Drop-in中Split Card最大
UIの自由度HPP色・レイアウト・ロゴDrop-in外観設定とCSSルールSplit Card入力欄ごとに制御
PCI-DSSの範囲HPPSAQ ADrop-inSAQ ASplit CardSAQ A
決済方法HPP対応するすべてDrop-in対応するすべてSplit Cardカードのみ
画面遷移HPPリダイレクトありDrop-in自サイト内(iframe)Split Card自サイト内(iframe)

とにかく早く決済を通したいならHPP、自サイトの画面を保ったまま複数の決済方法を出したいならDrop-in、カード入力の見た目を細かく作り込みたいならSplit Card、という振り分けです。サブスクリプションや定期課金はBilling Hosted Checkoutで、HPPとは扱うAPIそのものが違います。airwallex-hpp の説明文には「サブスクリプションには使わない」と明記されており、取り違えた依頼をすると別のスキルを案内される作りです。

HPPのスキルが書くコードの形

HPPのリファレンスでは、フロントエンドは @airwallex/components-sdk の init を呼んでから redirectToCheckout を実行する流れです。

npm install @airwallex/components-sdk
import { init } from '@airwallex/components-sdk';
 
const { payments } = await init({
  env: 'demo',  // 本番は 'prod'
  enabledElements: ['payments'],
});
 
payments.redirectToCheckout({
  intent_id: 'replace-with-your-intent-id',
  client_secret: 'replace-with-your-client-secret',
  currency: 'USD',
  country_code: 'US',
  successUrl: 'https://yoursite.com/payment-success',
});

上は公式リファレンスの例に沿った形です。Claudeの実出力ではなく、スキルが拠り所にする断片だと考えてください。enabledElements: ['payments'] を指定しないと payments が undefined になります。Drop-inも同じく、init が終わる前に createElement('dropIn', …) を呼ぶと、マウント後のコンテナが空のままになります。

バックエンドで作るのはCustomerとPaymentIntentです。作り方は、スキルが取得を指示するAirwallexの「Payments integration notes for AI agents」に書かれています。

決済完了の判定はリダイレクトに頼らない

HPPのリファレンスには、見落としやすい注意が書かれています。決済後に successUrl へ戻った時点では、PaymentIntentがまだ PROCESSING のことがあります。3DS認証の直後などです。そのため、戻り先で1回だけ状態を引いても最終結果を取り逃がします。

参照ファイルが示す対処は2つです。バックエンドでPaymentIntentを数回ポーリングする方法と、payment_intent.succeeded のWebhookで受ける方法で、後者が望ましいとされています。リダイレクトだけで成功とみなさず、成功か失敗かを必ず画面に出す、という指針です。生成コードをレビューするときは、ここが守られているかを最初に見るとよいでしょう。

サブスクリプション課金とKYCのスキル

airwallex-billing-checkout は、他の4スキルと動き方が違います。argument-hint を持たず、最初に聞き取りを行ってから出力する内容を決めます。

聞き取りの最初の質問は、サブスクリプション(SUBSCRIPTION)、単発の請求書払い(PAYMENT)、カード保存だけ(SETUP)のどれかです。サブスクリプションなら無料トライアルの日数、クーポンの種類、価格モデルを続けて尋ねます。価格モデルは固定(FLAT)、数量単価(PER_UNIT)、段階課金(VOLUME と GRADUATED)から選びます。従量課金は価格モデルの種類ではなく、Priceに metered: true と meter_id を付けて、使用量をイベントとして送る方式だと明記されています。

SETUP モードは x-api-version が 2025-08-29 以降でないと使えません。スキルはAPIバージョンを日付で固定せず、.env の AIRWALLEX_X_API_VERSION から読む書き方を勧めています。ヘッダーを省略してアカウントの既定に頼る場合は、既定のバージョンが使う機能の最低条件を満たすかの確認が要ります。

airwallex-kyc は、コネクテッドアカウントのオンボーディングを埋め込みコンポーネント(embedded-kyc-component)かホスト型リンク(hosted-flow)のどちらかで組みます。2つは同時に指定できません。決済のスキル群とは領域が別なので、決済の依頼とKYCの依頼を混ぜないほうが、意図したスキルが選ばれます。

Claude Codeで頼むときの進め方

プラグインを入れただけでは、決済コードの責任はなくなりません。次の3点を決めてから頼むと、生成後の手戻りが減ります。

鍵をClaudeに読ませない

サンドボックスの認証情報は .env に置き、Claudeのファイルツールから読めないようにします。.claude/settings.json に Read の拒否ルールを書きます。

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

スキルのBilling向け記述も、コード例の機密値には <PLACEHOLDER> を使う方針です。鍵そのものをプロンプトに貼らず、環境変数の名前だけを教えて書かせます。秘密情報を .env から外す別の方法は1Passwordプラグインの記事で扱っています。

条件をCLAUDE.mdに固定する

決済方式や環境の取り違えは、毎回の依頼文に頼ると再発します。プロジェクトの前提を CLAUDE.md に書いておきます。

## 決済(Airwallex)
- 決済UIは Hosted Payment Page を使う。Drop-in と Split Card は使わない
- 接続先は常にサンドボックス(env は 'demo')。本番の切り替えは人間が行う
- 支払い完了の判定は payment_intent.succeeded の Webhook を正とする
- 鍵は .env の環境変数から読む。コードに直書きしない

こう書いておけば、「決済を付けて」という曖昧な依頼でも、スキルを選ぶ前提が揃います。本番への切り替えを人間に残すのは、後述するREADMEの注意書きとも整合します。

検証コマンドを走らせて読ませる

生成したら、型チェックやビルドを実行させ、出力を読んで直させます。スキルは検証の手段を持たないので、npm run build や npx tsc --noEmit など、プロジェクト既存のコマンドを依頼文に書きます。決済のテストにはテストカード番号のドキュメントが必要で、HPPなどのスキルは、利用者がテストデータを求めたときに参照するよう指示しています。

使う前に知っておく制約

READMEの「Important Notice」は、このプラグインをベータ機能と位置づけ、現状のまま提供するとしています。要点は4つです。

  • AIエージェントが実行した操作も、Airwallexの利用規約の対象になる
  • APIキーの管理と用途の限定は利用者の責任
  • 財務・法務・税務の助言は行わず、AIの出力は担当者が確認してから使う
  • 送金・為替取引・支払いといった資金の流出を伴う操作は、プラグインとして実行しない。APIに機能があっても、スキルは実行しないよう指示されている

最後の点は、生成コードの内容とは別の話です。エージェントが勝手に送金することはない、という設計の宣言です。一方で、生成された決済コードが本番で動いたときの課金処理は、あなたのアプリの責任になります。サンドボックスで通しきってから、人間が本番の認証情報に切り替える運用が前提です。

airwallex-ai-provider-card-mit は計画書を作る

AIサービス事業者向けのこのスキルは、他の5つと性質が違います。トークン残高のチャージ、低残高時の自動チャージ、定額サブスクリプションの更新を、事業者起点のカード課金で組むための計画書を作るスキルです。

コードを書く前に計画を固めることがルールで、既定の出力先はカレントのプロジェクトにある airwallex-ai-provider-card-mit-plan.md です。同名のファイルが既にある場合は、上書きの前に確認を取ります。スキル自体にSDKのコード例は含まれておらず、MCPで検証したフロント・バックエンドの例を計画書に載せる仕様です。定額更新と従量チャージは別の同意として扱う、といった設計判断も計画書に書かせます。AIの利用料金を自前の台帳で管理するプロダクト向けで、通常のECサイトには向きません。

プラグインが動かないとき

プラグインのインストールで依存パッケージの警告が出る場合は、packages are not installedの対処を確認してください。別のAPI連携の例として、動画生成APIを同じ形で組み込むRunwayのプラグインはRunway Devプラグインの記事で扱っています。

まとめ

airwallex-dev が効くのは、Airwallexで決済やサブスクリプションを組み込む実装作業です。選ぶ基準は、決済UIならHPP・Drop-in・Split Cardの3択、課金ならBilling、事業者向けの特殊な課金なら計画書のスキルです。MCPがサンドボックス向けである点と、READMEのベータ表記は、導入前に把握しておく点です。

最初の1本を頼むなら、CLAUDE.md に決済方式とサンドボックス固定を書き、鍵の Read を拒否したうえで、HPPのスキルから始めるのが最小の構成です。Webhookでの完了判定が生成コードに入っているかを確認し、サンドボックスで通ってから本番の設定を人の手で切り替えます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →