Customers API
概要
Customers APIを使用すると、保存された決済手段を持つ顧客プロファイルを作成および管理できます。クレジットカードを安全に保存し、リピーター顧客への請求を簡単に行い、顧客データを効率的に管理できます。
Customerとは
Customerは購入者を表すオブジェクトで、以下を含みます。
- 顧客情報 - メールアドレス、名前、説明
- 保存されたカード - 安全に保存された決済手段
- デフォルトカード - Chargeの主要な決済手段
- メタデータ - 記録用のカスタムデータ
- Charge履歴 - 顧客ごとの支払いを追跡
主な機能
安全なカード保存
- PCI準拠 - Omiseがカードを安全に保存
- 複数カード - 顧客ごとに複数の決済手段を保存
- デフォルトカード - 主要な決済手段を設定
- 機密データなし - 生のカード番号ではなく、カードTokenのみを保存
簡単な継続決済
- ワンクリック請求 - 新しいToken化なしで顧客に請求
- サブスクリプション - 継続課金に最適
- 保存された決済手段 - 顧客はカード詳細を再入力する必要がありません
- 顧客プロファイル - 顧客ごとの支払い履歴を追跡
柔軟な管理
- 顧客情報の更新 - メールアドレス、説明、メタデータの変更
- カード管理 - 決済手段の追加、更新、削除
- デフォルトカードの設定 - 請求するカードを選択
- すべての顧客をリスト表示 - 顧客データベースのページネーション
Customerの仕組み
Standard Flow
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Client │ │ Your │ │ Omise │
│ Browser │ │ Server │ │ API │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
│ 1. Enter card │ │
├──────────────────>│ │
│ │ │
│ 2. Create token │ │
│ (Omise.js) │ │
├──────────────────────────────────────>│
│ │ │
│ 3. Return token │ │
│<──────────────────────────────────────┤
│ │ │
│ 4. Send token │ │
├──────────────────>│ │
│ │ │
│ │ 5. Create customer│
│ │ (with token) │
│ ├──────────────────>│
│ │ │
│ │ 6. Return customer│
│ │ (card saved) │
│ │<──────────────────┤
│ │ │
│ 7. Future charges │ │
│ (no new token) │ │
│ ├──────────────────>│
│ │ │
実装手順
- 初回: カー ドをToken化 → TokenでCustomerを作成
- カード保存: カードが添付されたCustomerプロファイルが作成されます
- 将来の支払い: Customer IDで直接請求（新しいTokenは不要）
APIエンドポイント
| Method | Endpoint | Description |
|---|---|---|
| POST | /customers | 新しいCustomerを作成 |
| GET | /customers/:id | Customerの詳細を取得 |
| PATCH | /customers/:id | Customer情報を更新 |
| DELETE | /customers/:id | Customerを削除 |
| GET | /customers | すべてのCustomerをリスト表示 |
| POST | /customers/:id/cards | Customerにカードを追加 |
| GET | /customers/:id/cards/:card_id | カードの詳細を取得 |
| PATCH | /customers/:id/cards/:card_id | カード情報を更新 |
| DELETE | /customers/:id/cards/:card_id | Customerからカードを削除 |
クイックスタート
カード付きCustomerの作成
// Client-side: Tokenize card
Omise.setPublicKey('pkey_test_YOUR_PUBLIC_KEY');
Omise.createToken('card', cardData, async (status, response) => {
if (status === 200) {
// Server-side: Create customer
const customer = await omise.customers.create({
email: 'john@example.com',
description: 'John Doe',
card: response.id // Token from Omise.js
});
console.log('Customer created:', customer.id);
console.log('Card saved:', customer.default_card);
}
});
既存Customerへの請求
// No token needed - charge customer directly
const charge = await omise.charges.create({
customer: 'cust_test_5xuy4w91xqz7d1w9u0t',
amount: 100000,
currency: 'thb',
description: 'Order #5678'
});
console.log('Charged customer:', charge.customer);
console.log('Status:', charge.status);
追加カードの追加
// Tokenize new card
Omise.createToken('card', newCardData, async (status, response) => {
if (status === 200) {
// Add card to existing customer
const card = await omise.customers.update('cust_test_5xuy4w91xqz7d1w9u0t', {
card: response.id
});
console.log('Card added:', card.id);
}
});
一般的な使用例
サブスクリプション課金
一度Customerを作成し、毎月自動的に請求します。
// One-time setup
const customer = await omise.customers.create({
email: 'subscriber@example.com',
card: tokenId
});
// Monthly billing (automated)
setInterval(async () => {
await omise.charges.create({
customer: customer.id,
amount: 99900, // $9.99/month
currency: 'usd',
description: 'Monthly subscription'
});
}, 30 * 24 * 60 * 60 * 1000); // 30 days
後で使用するためのカード保存
顧客がカードを保存し、後で購入を決定します。
// Checkout: Save card
const customer = await omise.customers.create({
email: 'shopper@example.com',
card: tokenId,
metadata: { loyalty_id: '12345' }
});
// Later: Quick checkout
const charge = await omise.charges.create({
customer: customer.id,
amount: 250000,
currency: 'thb'
});
複数の決済手段
顧客が複数のカードを管理します。
// Add multiple cards
await omise.customers.update(customerId, { card: token1 });
await omise.customers.update(customerId, { card: token2 });
// List customer's cards
const customer = await omise.customers.retrieve(customerId);
console.log('Cards:', customer.cards.data);
// Charge specific card
await omise.charges.create({
customer: customerId,
card: customer.cards.data[1].id, // Second card
amount: 100000
});
Customerのライフサイクル
状態
| State | Description | Can Charge? |
|---|---|---|
| Active | 有効なカードを持つCustomer | ✅ はい |
| No Cards | 決済手段のないCustomer | ❌ いいえ |
| Deleted | 削除されたCustomer | ❌ いいえ |
カード管理
- カードの追加: Tokenを作成 → TokenでCustomerを更新
- デフォルトの設定:
default_cardパラメータでCustomerを更新 - カードの削除: CustomerからCardを削除
- カードの更新: 有効期限、名前などを更新
セキュリティのベストプラクティス
✅ これを行う
- Tokenを使用してカードを追加（生のカードデータを送信しない）
- Customer IDを保存データベースに
- 顧客の所有権を確認請求を許可する前に
- メタデータを使用内部追跡用に
- 認証を実装顧客データを保護するために
- カードエラーを処理適切に（期限切れ、拒否）
- 古いCustomerを削除不要になったら
❌ これをしない
- カード番号を送信しないサーバーに
- Customer IDを公開しない公開的に
- 承認をスキップしない（ユーザーがCustomerを所有していることを確認）
- 機密データを保存しないメタデータに
- 許可なく請求しない（PCI要件）
- 非アクティブなCustomerを保持しない無期限に
データプライバシー
GDPR準拠
- Customerを削除要求された場合
- 顧客データをエクスポート要求に応じて
- 最小限のメタデータを使用（必要なもののみ）
- Customer IDを保護（URLに公開しない）
PCI準拠
- 生のカード番号を保存しない
- Tokenを使用すべてのカード操作に
- アクセスを制限顧客データへの
- 監査顧客データへのアクセスを
テスト
テストCustomer
テストTokenでテストCustomerを作成します。
// Test mode customer
const customer = await omise.customers.create({
email: 'test@example.com',
card: 'tokn_test_no1t4tnemucod0e51mo'
});
// Customer ID starts with cust_test_
console.log(customer.id); // cust_test_...
テストカード
テストカード番号を使用します。
4242424242424242- Visa（成功）4000000000000002- Visa（拒否）5555555555554444- Mastercard（成功）
エラー処理
一般的なCustomerエラー:
| Error Code | Description | Solution |
|---|---|---|
used_token | Tokenは既に使用されています | 新しいTokenを作成 |
invalid_card | カードが無効です | カードの詳細を検証 |
customer_not_found | Customer IDが存在しません | Customer IDを確認 |
card_not_found | カードがCustomerに属していません | Card IDを確認 |
APIリファレンス
- Customerの作成 - POST /customers
- Customerの取得 - GET /customers/:id
- Customerの更新 - PATCH /customers/:id
- Customerの削除 - DELETE /customers/:id
- Customerのリスト表示 - GET /customers
関連リソース
統合ガイド
サポートが必要ですか？顧客管理ガイドをご確認いただくか、support@omise.coまでお問い合わせください