Tokens API
概要
Tokens APIを使用すると、サーバー上で機密性の高いカードデータを扱うことなく、クレジットカード情報を安全にトークン化できます。Tokenは、Chargeの作成に使用できるカードデータへの使い捨ての暗号化された参照です。
Tokenとは
Tokenは、クレジットカード情報の一時的な使い捨て表現であり、以下の特徴があります。
- 使用後に期限切れ - 各TokenはChargeの作成または顧客への添付に一度だけ使用できます
- カードデータを保護 - サーバーは生のカード詳細を 決して扱いません
- PCI準拠を可能に - PCI準拠範囲を大幅に削減します
- 即座に検証 - トークン化中にカード詳細が検証されます
主な機能
セキュリティ第一
- 公開鍵認証 - 公開鍵を使用（クライアント側コードで公開しても安全）
- 使い捨てToken - Charge作成後はTokenを再利用できません
- 機密データの保存なし - カードデータはサーバーに触れません
- PCI DSS準拠 - 最も厳格なセキュリティ基準を満たします
簡単な統合
- クライアント側トークン化 - ブラウザ/モバイルアプリから直接Tokenを作成
- Omise.jsライブラリ - 簡単な統合のための既製JavaScriptライブラリ
- モバイルSDK - ネイティブiOSおよびAndroid SDK利用可能
- サーバー間通信 - 必要に応じてサーバー側トークン化用のAPI利用可能
柔軟性
- すべてのカードタイプに対応 - Visa、Mastercard、JCBなど
- 3D Secureサポート - 自動3DS処理
- カード検証 - カード番号、CVV、有効期限を検証
- 国際対応 - 任意の国のカードを処理
Tokenの仕組み
標準フロー
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Client │ │ Omise.js│ │ Your │ │ Omise │
│ Browser │ │ Library │ │ Server │ │ API │
└────┬──── ┘ └────┬────┘ └────┬────┘ └────┬────┘
│ │ │ │
│ 1. Enter card │ │ │
├──────────────────>│ │ │
│ │ │ │
│ │ 2. Create token │ │
│ │ (with public key) │
│ ├──────────────────────────────────────>│
│ │ │ │
│ │ 3. Return token │ │
│ │<──────────────────────────────────────┤
│ │ │ │
│ 4. Send token ID │ │ │
├──────────────────────────────────────>│ │
│ │ │ │
│ │ │ 5. Create charge │
│ │ │ (with secret key)
│ │ ├──────────────────>│
│ │ │ │
│ │ │ 6. Charge result │
│ │ │<──────────────────┤
│ │ │ │
│ 7. Show result │ │ │
│<──────────────────────────────────────┤ │
│ │ │ │
実装手順
- クライアント側: 決済フォームでカード詳細を収集
- クライアント側: Omise.jsを使用して公開鍵でカードデータをトークン化
- クライアント側: Token IDをサーバーに送信（安全 - 使い捨て）
- サーバー側: シークレットキーでToken IDを使用してChargeを作成
- サーバー側: 決済結果をクライアントに返す
Tokenのライフサイクル
状態
| State | Description | Chargeを作成可能? |
|---|---|---|
| Active | 新規作成、未使用のToken | ✅ はい |
| Used | Charge/顧客の 作成に使用されたToken | ❌ いいえ - エラー "used_token" |
| Expired | 30分以上経過したToken | ❌ いいえ - エラー "token_expired" |
状態遷移
Tokenは以下のトリガーに基づいて状態を遷移します。
┌─────────┐
│ Active │ ← Token created via Omise.js or API
└────┬────┘
│
├─────────────┐
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ Used │ │ Expired │
└─────────┘ └─────────┘
Transition Triggers:
| From State | To State | Trigger | Error Code |
|---|---|---|---|
| Active → Used | Token used in POST /charges or POST /customers/:id/cards | - | |
| Active → Expired | 30 minutes pass since creation | token_expired | |
| Used → same | Attempt to reuse token | used_token | |
| Expired → same | Attempt to use expired token | token_expired |
状態遷移の例：
// 1. Tokenを作成（Active状態）
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 (Active)
// 2. Chargeを作成（Active → Used）
const charge = await omise.charges.create({
amount: 100000,
currency: 'thb',
card: token.id
});
// TokenはUsedとしてマークされます
// 3. 再利用を試みる（エラー: used_token）
try {
await omise.charges.create({
amount: 50000,
currency: 'thb',
card: token.id // 同じToken
});
} catch (error) {
console.error(error.code); // "used_token"
console.error(error.message); // "token was already used"
}
// 4. 30分後にTokenが期限切れ（Active → Expired）
// 自動 - アクションは不要
// 30分以上未使用の場合、token.used === falseですが、APIはtoken_expiredを返します
有効期限ルール
- 自動有効期限: 作成から30分後
- 使い捨て: 最初のCharge/顧客への添付後に即座に使用済みとマーク
- 再利用不可: 同じ顧客に対しても再利用不可
- 不可逆: 使用済みおよび期限切れTokenは再アクティブ化不可
API エンドポイント
| Method | Endpoint | Description |
|---|---|---|
| POST | /tokens | カードデータから新しいTokenを作成 |
| GET | /tokens/:id | Token情報を取得 |
クイックスタート
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) {
// 成功 - Token作成完了
const tokenId = response.id;
// 4. Tokenをサーバーに送信
fetch('/charge', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token: tokenId, amount: 100000 })
})
.then(res => res.json())
.then(data => {
console.log('Charge created:', data.id);
})
.catch(err => {
console.error('Charge failed:', err);
alert('決済処理に失敗しました。もう一度お試しください。');
});
} else {
// トークン化失敗 - 特定のエラーを処理
console.error('Tokenization failed:', 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'
});
// クライアントからTokenを受信
app.post('/charge', async (req, res) => {
const { token, amount } = req.body;
try {
// Tokenを使用してChargeを作成
const charge = await omise.charges.create({
amount: amount,
currency: 'thb',
card: token // ここでTokenを使用
});
res.json({ success: true, charge: charge });
} catch (error) {
res.status(400).json({ error: error.message });
}
});
一般的な使用例
単一決済
Token作成 → Charge作成 → 完了
// クライアント: トークン化
Omise.createToken('card', cardData, (status, response) => {
// サーバー: Charge
omise.charges.create({ card: response.id, amount: 100000 });
});
後で使用するためにカードを保存
Token作成 → 顧客に添付 → 顧客をCharge
// Tokenで顧客を作成
const customer = await omise.customers.create({
email: 'john@example.com',
card: tokenId
});
// 後で: 顧客の保存済みカードをCharge
const charge = await omise.charges.create({
customer: customer.id,
amount: 100000
});
顧客ごとに複数のカード
Token作成 → 既存の顧客に添付 → Chargeするカードを選択
// 顧客にカードを追加
const card = await omise.customers.updateCard(customerId, {
card: tokenId
});
// 特定のカードをCharge
const charge = await omise.charges.create({
customer: customerId,
card: card.id,
amount: 100000
});
セキュリティのベストプラクティス
✅ 推奨事項
- HTTPSを使用 すべての決済フォームページで
- Omise.jsを使用 クライアント側トークン化に
- サーバーで検証 - クライアント側の検証だけを信頼しない
- Tokenをログに記録しない プレーンテキストで
- 公開鍵はクライアント側のみで使用
- シークレットキーはサーバー側のみで使用
- CSPヘッダーを実装 XSS攻撃を防止するため
❌ 非推奨事項
- カードデータをサーバーに送信しない（トークン化を使用）
- カード番号をデータベースに保存しない
- Tokenを再利用しない（使い捨て）
- シークレットキーを公開しない クライアント側コードで
- サーバー側検証をスキ ップしない
- サーバーでトークン化しない 必要でない限り（クライアント側を使用）
テスト
テストカード番号
テストモードでこれらのテストカードを使用してください:
| カード番号 | 説明 | 結果 |
|---|---|---|
| 4242424242424242 | Visa | Chargeに成功 |
| 5555555555554444 | Mastercard | Chargeに成功 |
| 4111111111111111 | Visa | Chargeに成功 |
| 4000000000000002 | Visa | カード拒否 |
テストモード
- テスト公開鍵を使用してください:
pkey_test_... - テストキーで作成されたTokenはテストシークレットキーでのみ動作します
- テストモードでは実際のお金は課金されません
エラー処理
一般的なTokenエラー:
| エラーコード | 説明 | 解決方法 |
|---|---|---|
invalid_card | 無効なカード番号 | カード番号形式を確認 |
invalid_expiration_date | 無効または期限切れの日付 | 有効期限の月/年を確認 |
invalid_security_code | 無効なCVV | CVVが3〜4桁であることを確認 |
used_token | Token既に使用済み | 新しいTokenを作成 |
token_not_found | Tokenが存在しない | Token IDを確認 |
APIリファレンス
関連リソース
SDKとライブラリ
- Omise.js - JavaScriptライブラリ
- iOS SDK - ネイティブiOS
- Android SDK - ネイティブAndroid
- サーバーSDK - Ruby、Python、PHP、Node.js、Go、Java、.NET
サポートが必要ですか？ セキュリティガイドを確認するか、support@omise.coまでお問い合わせください