トークン API
概要
トークン APIを使用すると、サーバーで機密性の高いカードデータを処理することなく、クレジットカード情報を安全にトークン化できます。トークンは、課金を作成するために使用できるカードデータへの使い捨ての暗号化された参照です。
トークンとは
トークンは、クレジットカード情報の一時的な使い捨て表現で、以下の特徴があります:
- 使用後に失効 - 各トークンは、課金の作成または顧客への紐付けに一度だけ使用できます
- カードデータの保護 - サーバーが生のカード情報を処理することはありません
- PCIコンプライアンスの実現 - PCIコンプライアンスの範囲を大幅に縮小します
- 即時検証 - トークン化の際にカード情報が検証されます
主な機能
セキュリティ優先
- 公開鍵認証 - クライアントサイドのコードで安全に公開できる公開鍵を使用
- 使い捨てトークン - 課金作成後にトークンを再利用することはできません
- 機密データの非保存 - カードデータがサーバーに触れることはありません
- PCI DSS準拠 - 最も厳格なセキュリティ基準を満たしています
簡単な統合
- クライアントサイドのトークン化 - ブラウザ/モバイルアプリから直接トークンを作成
- Omise.jsライブラリ - 簡単な統合のための構築済みJavaScriptライブラリ
- モバイルSDK - ネイティブiOSおよびAndroid SDKが利用可能
- サーバー間通信 - 必要に応じてサーバーサイドのトークン化用APIも利用可能
柔軟性
- すべてのカードタイプに対応 - Visa、Mastercard、JCBなど
- 3Dセキュアサポート - 自動3DS処理
- カード検証 - カード番号、CVV、有効期限を検証
- 国際対応 - あらゆる国のカードを処理
トークンの仕組み
標準フロー
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ クライアント│ │ Omise.js│ │ お客様の │ │ Omise │
│ ブラウザ │ │ ライブラリ│ │ サーバー │ │ API │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
│ │ │ │
│ 1. カード情報入力 │ │ │
├──────────────────>│ │ │
│ │ │ │
│ │ 2. トークン作成 │ │
│ │ （公開鍵を使用） │
│ ├──────────────────────────────────────>│
│ │ │ │
│ │ 3. トークン返却 │ │
│ │<──────────────────────────────────────┤
│ │ │ │
│ 4. トークンID送信 │ │ │
├──────────────────────────────────────>│ │
│ │ │ │
│ │ │ 5. 課金作成 │
│ │ │ （秘密鍵を使用）
│ │ ├──────────────────>│
│ │ │ │
│ │ │ 6. 課金結果 │
│ │ │<──────────────────┤
│ │ │ │
│ 7. 結果表示 │ │ │
│<──────────────────────────────────────┤ │
│ │ │ │
実装手順
- クライアントサイド: 支払いフォームでカード情報を収集
- クライアントサイド: Omise.jsを使用して公開鍵でカードデータをトークン化
- クライアントサイド: トークンIDをサーバーに送信（使い捨てなので安全）
- サーバーサイド: 秘密鍵を使用してトークンIDで課金を作成
- サーバーサイド: 支払い結果をクライアントに返却
トークンのライフサイクル
状態
| 状態 | 説明 | 課金作成可能？ |
|---|---|---|
| アクティブ | 新しく作成された未使用のトークン | ✅ はい |
| 使用済み | 課金/顧客作成に使用されたトークン | ❌ いいえ - エラー "used_token" |
| 期限切れ | 30分以上経過したトークン | ❌ いいえ - エラー "token_expired" |
状態遷移
トークンは以下のトリガーに基づいて状態が遷移します:
┌─────────┐
│ アクティブ│ ← Omise.jsまたはAPIで作成されたトークン
└────┬────┘
│
├─────────────┐
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ 使用済み │ │ 期限切れ │
└─────────┘ └─────────┘
遷移トリガー:
| 遷移元 | 遷移先 | トリガー | エラーコード |
|---|---|---|---|
| アクティブ → 使用済み | POST /charges または POST /customers/:id/cards でトークンが使用された | - | |
| アクティブ → 期限切れ | 作成から30分が経過 | token_expired | |
| 使用済み → 同じ | トークンの再利用を試行 | used_token | |
| 期限切れ → 同じ | 期限切れトークンの使用を試行 | token_expired |
状態遷移の例:
// 1. トークンを作成（アクティブ状態）
const token = await omise.tokens.create({
card: {
number: '4242424242424242',
expiration_month: 12,
expiration_year: 2027,
security_code: '123',
name: 'JOHN DOE'
}
});
console.log(token.used); // false（アクティブ）
// 2. 課金を作成（アクティブ → 使用済み）
const charge = await omise.charges.create({
amount: 100000,
currency: 'thb',
card: token.id
});
// トークンは使用済みとしてマークされました
// 3. 再利用を試行（エラー: used_token）
try {
await omise.charges.create({
amount: 50000,
currency: 'thb',
card: token.id // 同じトークン
});
} catch (error) {
console.error(error.code); // "used_token"
console.error(error.message); // "token was already used"
}
// 4. 30分後にトークンが期限切れ（アクティブ → 期限切れ）
// 自動的に発生 - アクションは不要
// 30分以上未使用の場合、token.used === false だが APIは token_expired を返す
有効期限ルール
- 自動期限切れ: 作成から30分後
- 使い捨て: 最初の課金/顧客への紐付け後、すぐに使用済みとしてマーク
- 再利用不可: 同じ顧客に対しても再利用できません
- 不可逆: 使用済みおよび期限切れのトークンは再有効化できません
APIエンドポイント
| メソッド | エンドポイント | 説明 |
|---|---|---|
| POST | /tokens | カードデータから新しいトークンを作成 |
| GET | /tokens/:id | トークン情報を取得 |
クイックスタート
Omise.jsの使用（推奨）
<!-- 1. Omise.jsを読み込む -->
<script src="https://cdn.omise.co/omise.js"></script>
<script>
// 2. 公開鍵を設定
Omise.setPublicKey('pkey_test_YOUR_PUBLIC_KEY');
// 3. カードをトークン化
const cardData = {
name: 'JOHN DOE',
number: '4242424242424242',
expiration_month: 12,
expiration_year: 2025,
security_code: '123'
};
Omise.createToken('card', cardData, (statusCode, response) => {
if (statusCode === 200) {
// 成功 - トークン作成完了
const tokenId = response.id;
// 4. トークンをサーバーに送信
fetch('/charge', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token: tokenId, amount: 100000 })
})
.then(res => res.json())
.then(data => {
console.log('課金が作成されました:', data.id);
})
.catch(err => {
console.error('課金に失敗しました:', err);
alert('決済処理に失敗しました。もう一度お試しください。');
});
} else {
// トークン化失敗 - 特定のエラーを処理
console.error('トークン化 に失敗しました:', response);
// 一般的なエラーコードを処理
switch (response.code) {
case 'invalid_card':
alert('無効なカード番号です。確認してもう一度お試しください。');
break;
case 'invalid_expiration_date':
alert('無効な有効期限です。確認してもう一度お試しください。');
break;
case 'invalid_security_code':
alert('無効なCVV/セキュリティコードです。確認してもう一度お試しください。');
break;
case 'network_error':
alert('ネットワークエラーです。接続を確認してもう一度お試しください。');
break;
default:
alert('決済に失敗しました: ' + response.message);
}
}
});
</script>
サーバーサイド処理
// Node.jsの例
const omise = require('omise')({
secretKey: 'skey_test_YOUR_SECRET_KEY'
});
// クライアントからトークンを受信
app.post('/charge', async (req, res) => {
const { token, amount } = req.body;
try {
// トークンで課金を作成
const charge = await omise.charges.create({
amount: amount,
currency: 'thb',
card: token // ここでトークンを使用
});
res.json({ success: true, charge: charge });
} catch (error) {
res.status(400).json({ error: error.message });
}
});
一般的なユースケース
単発決済
トークン作成 → 課金作成 → 完了
// クライアント: トークン化
Omise.createToken('card', cardData, (status, response) => {
// サーバー: 課金
omise.charges.create({ card: response.id, amount: 100000 });
});
後で使用するためにカードを保存
トークン作成 → 顧客に紐付け → 顧客に課金
// トークンで顧客を作成
const customer = await omise.customers.create({
email: 'john@example.com',
card: tokenId
});
// 後で: 顧客の保存されたカードに課金
const charge = await omise.charges.create({
customer: customer.id,
amount: 100000
});
顧客ごとに複数のカード
トークン作成 → 既存の顧客に紐付け → 課金するカードを選択
// 顧客にカードを追加
const card = await omise.customers.updateCard(customerId, {
card: tokenId
});
// 特定のカードに課金
const charge = await omise.charges.create({
customer: customerId,
card: card.id,
amount: 100000
});
セキュリティのベストプラクティス
推奨事項
- HTTPSを使用: 支払いフォームのあるすべてのページに使用
- Omise.jsを使用: クライアントサイドのトークン化に使用
- サーバーで検証: クライアントサイドの検証だけに頼らない
- トークンをプレーンテキストでログに記録しない
- クライアントサイドでは公開鍵のみを使用
- サーバーサイドでは 秘密鍵のみを使用
- CSPヘッダーを実装: XSS攻撃を防止
禁止事項
- カードデータをサーバーに送信しない（トークン化を使用）
- カード番号をデータベースに保存しない
- トークンを再利用しない（使い捨て）
- 秘密鍵をクライアントサイドのコードに公開しない
- サーバーサイドの検証をスキップしない
- 必要がない限りサーバーでトークン化しない（クライアントサイドを使用）
テスト
テストカード番号
テストモードでこれらのテストカードを使用してください:
| カード番号 | 説明 | 結果 |
|---|---|---|
| 4242424242424242 | Visa | 課金成功 |
| 5555555555554444 | Mastercard | 課金成功 |
| 4111111111111111 | Visa | 課金成功 |
| 4000000000000002 | Visa | カード拒否 |
テストモード
- テスト用の公開鍵を使用:
pkey_test_... - テストキーで作成されたトークンは、テスト用秘密鍵でのみ機能します
- テストモードでは実際の課金は発生しません
エラー処理
一般的なトークンエラー:
| エラーコード | 説明 | 解決方法 |
|---|---|---|
invalid_card | 無効なカード番号 | カード番号の形式を確認 |
invalid_expiration_date | 無効または期限切れの日付 | 有効期限の月/年を確認 |
invalid_security_code | 無効なCVV | CVVが3〜4桁であることを確認 |
used_token | トークンは既に使用済み | 新しいトークンを作成 |
token_not_found | トークンが存在しない | トークンIDを確認 |
APIリファレンス
関連リソース
SDKとライブラリ
- Omise.js - JavaScriptライブラリ
- iOS SDK - ネイティブiOS
- Android SDK - ネイティブAndroid
- サーバーSDK - Ruby、Python、PHP、Node.js、Go、Java、.NET
お困りですか？ セキュリティガイドを確認するか、support@omise.co までお問い合わせください