海外決済サービスと格闘した3週間

はじめに

海外向けのWebサービスで決済機能を実装することになりました。

マジで大変でした。

ドキュメントは全部英語以外の言語、TypeScriptの型定義なし、開発環境と本番環境で仕様が違う...
何度も心が折れかけましたが、なんとか実装完了できました。

この記事は、同じような状況で困っている人の参考になれば嬉しいです🙏

TL;DR

• 英語以外のドキュメント、特に画像内テキストの翻訳が地獄
• 型定義を自作するハメに
• dev環境でテストできない機能が本番必須
• Geminiの翻訳・要約がガチで救世主だった

第一の壁：全部英語以外のドキュメント

公式ドキュメントを開いた瞬間、全部読めない言語。

Google翻訳で乗り切ろうとしたが...

テキスト部分は、なんとかGoogle翻訳で理解できました。

でも問題は 画像内のテキスト。

処理フローやシーケンス図が何十枚もあるのに、画像内の文字が翻訳できない。
処理の流れを理解するには、この画像が一番重要なのに...

第二の壁：TypeScriptで型がない地獄

この決済サービス、フロントエンド用のJavaScript SDKはありました。
でも バックエンド用のSDK（npmパッケージ）が存在しない。

つまり

• フロントエンド：SDKあり（でも型定義なし）
• バックエンド：生APIを直接叩くしかない

型がないならTypeScriptの意味ないじゃん😇

仕方ないので、フロントエンド・バックエンド両方の型定義を自作することになりました。

// フロントエンド：SDKのグローバル変数の型定義
declare global {
  interface Window {
    TPDirect: {
      card: {
        getPrime: (callback: (result: any) => void) => void 
      }
    }
  }
}

// バックエンド：APIレスポンスの型を推測で作成
interface PayByPrimeResponse {
  status: number  // ← 0が成功らしい（たぶん）
  msg: string
  rec_trade_id?: string
  bank_transaction_id?: string
  // 他にもフィールドありそうだけど分からん
}

「たぶんこう」だらけで不安しかない...

第三の壁：開発環境でテストできないもどかしさ

一番ヤバかったのが 3D Secure です。

• 開発環境（Sandbox）: 3D Secureは使わない ❌
• 本番環境（Production）: 3D Secureは必須です ✅

3D Secureって、決済中にユーザーを銀行の認証ページにリダイレクトする複雑なフローなんです。
それを開発環境でテストできないって...

本番デプロイして初めて見るエラー

{
  "status": -1,
  "msg": "3D Secure authentication URL is required"
}

どこに設定するんですか...？（ドキュメント漁り直し）

本番でしか動かないコード書くの、めちゃくちゃ怖かったです。

転機：Geminiとの出会い

2週間格闘して、心が折れかけてた時に Gemini を使ってみました。
ちょうどこの時期に社内のGoogle Workspaceを有料プランにあげたのがタイミングよかったです。

画像内テキストも翻訳してくれる！

Geminiに画像をアップロードして「この処理フローを日本語で説明して」って頼んだら...

Gemini：この図は以下の処理フローを示しています：

1. フロントエンドでカード番号を入力
2. getPrime() でPrimeトークンを取得
3. Primeをバックエンドに送信
4. Pay By Prime APIを呼び出し
5. 3D Secure必要時は認証URLが返る
...

重要ポイント：
- Primeは1回限り有効
- 3D Secureは本番環境のみ

神か？

今まで何時間もかけて理解しようとしてた内容が、一瞬で分かりました。

長文ドキュメントも一瞬で要約

数十ページのAPIドキュメントも、Geminiに投げれば要約してくれます。

私：実装時の注意点を教えて

Gemini：主な注意点：

1. primeトークンは1回限り有効
2. 金額は現地通貨の最小単位で指定
3. 電話番号はE.164形式が必須
4. 3D Secureは本番環境のみ
...

めちゃくちゃ助かる... 😭

エラーメッセージも即座に理解

実装中に出た現地語のエラーメッセージも、Geminiに聞けば一発解決。

Google翻訳の直訳だと意味不明だったのが、Geminiなら文脈を理解して
「カード所有者の電話番号の形式が正しくありません」みたいに分かりやすく教えてくれました。

学んだこと

開発環境と本番環境の差異に注意

決済サービスは特に、セキュリティ機能が環境で違うことが多い。
事前確認が超重要です。

AI翻訳ツールをフル活用

特に効果的だったのは

• 画像内テキストの翻訳: Gemini最高
• 長文の要約: 数十ページが数分で理解できる
• エラーメッセージの解読: 即座に解決

令和に感謝💃

おわりに

海外の決済サービスとの格闘、大変でしたがいい経験になりました。

言語の壁はAIツールで乗り越えられる って分かったのが大きいです。
あと紹介忘れていましたが、catnoseさんのNaniもかなり使わせていただきました。あれ神です。

同じような状況で困っている人の助けになれば幸いです