メインコンテンツへスキップ
バージョン: 最新版

Customers API

概要​

Customers APIを使用すると、保存された支払い方法を持つ顧客プロファイルを作成および管理できます。クレジットカードを安全に保存し、リピーター顧客に簡単に課金し、顧客データを効率的に管理できます。

顧客とは？​

顧客はバイヤーを表すオブジェクトで、以下を含みます：

  • 顧客情報 - メールアドレス、名前、説明
  • 保存されたカード - 安全に保存された支払い方法
  • デフォルトカード - 課金のための主要な支払い方法
  • メタデータ - 記録用のカスタムデータ
  • 課金履歴 - 顧客ごとの支払いを追跡

主な機能​

安全なカード保管​

  • PCIコンプライアンス - カードはOmiseによって安全に保存
  • 複数カード - 顧客ごとに複数の支払い方法を保存
  • デフォルトカード - 主要な支払い方法を設定
  • 機密データなし - 生のカード番号ではなくカードトークンのみを保存

簡単なリピート支払い​

  • ワンクリック課金 - 新しいトークン化なしで顧客に課金
  • サブスクリプション - 定期請求に最適
  • 保存された支払い方法 - 顧客がカード詳細を再入力する必要なし
  • 顧客プロファイル - 顧客ごとの支払い履歴を追跡

柔軟な管理​

  • 顧客情報の更新 - メール、説明、メタデータの変更
  • カードの管理 - 支払い方法の追加、更新、削除
  • デフォルトカードの設定 - 課金するカードを選択
  • 全顧客の一覧 - 顧客データベースをページネーション

顧客の仕組み​

標準フロー​

┌─────────┐         ┌─────────┐         ┌─────────┐
│ クライアント │         │ あなたの │         │ Omise   │
│ ブラウザ │         │ サーバー │         │ API     │
└────┬────┘         └────┬────┘         └────┬────┘
     │                   │                   │
     │ 1. カード入力     │                   │
     ├──────────────────>│                   │
     │                   │                   │
     │ 2. トークン作成   │                   │
     │   (Omise.js)      │                   │
     ├──────────────────────────────────────>│
     │                   │                   │
     │ 3. トークン返却   │                   │
     │<──────────────────────────────────────┤
     │                   │                   │
     │ 4. トークン送信   │                   │
     ├──────────────────>│                   │
     │                   │                   │
     │                   │ 5. 顧客作成       │
     │                   │   (トークンで)    │
     │                   ├──────────────────>│
     │                   │                   │
     │                   │ 6. 顧客返却       │
     │                   │   (カード保存済み) │
     │                   │<──────────────────┤
     │                   │                   │
     │ 7. 将来の課金     │                   │
     │   (新トークン不要) │                   │
     │                   ├──────────────────>│
     │                   │                   │

実装手順​

  1. 初回: カードをトークン化 → トークンで顧客を作成
  2. カード保存: カードが添付された顧客プロファイルが作成される
  3. 将来の支払い: 顧客IDで直接課金（新しいトークン不要）

APIエンドポイント​

メソッドエンドポイント説明
POST/customers新しい顧客を作成
GET/customers/:id顧客詳細を取得
PATCH/customers/:id顧客情報を更新
DELETE/customers/:id顧客を削除
GET/customersすべての顧客を一覧
POST/customers/:id/cards顧客にカードを追加
GET/customers/:id/cards/:card_idカード詳細を取得
PATCH/customers/:id/cards/:card_idカード情報を更新
DELETE/customers/:id/cards/:card_id顧客からカードを削除

クイックスタート​

カードで顧客を作成​

// クライアント側: カードをトークン化
Omise.setPublicKey('pkey_test_YOUR_PUBLIC_KEY');
Omise.createToken('card', cardData, async (status, response) => {
  if (status === 200) {
    // サーバー側: 顧客を作成
    const customer = await omise.customers.create({
      email: 'john@example.com',
      description: 'John Doe',
      card: response.id  // Omise.jsからのトークン
    });

    console.log('顧客が作成されました:', customer.id);
    console.log('カードが保存されました:', customer.default_card);
  }
});

既存の顧客に課金​

// トークン不要 - 顧客に直接課金
const charge = await omise.charges.create({
  customer: 'cust_test_5xuy4w91xqz7d1w9u0t',
  amount: 100000,
  currency: 'thb',
  description: '注文 #5678'
});

console.log('顧客に課金しました:', charge.customer);
console.log('ステータス:', charge.status);

追加カードを追加​

// 新しいカードをトークン化
Omise.createToken('card', newCardData, async (status, response) => {
  if (status === 200) {
    // 既存の顧客にカードを追加
    const card = await omise.customers.update('cust_test_5xuy4w91xqz7d1w9u0t', {
      card: response.id
    });

    console.log('カードが追加されました:', card.id);
  }
});

一般的なユースケース​

サブスクリプション請求​

顧客を一度作成し、毎月自動課金：

// 一度きりのセットアップ
const customer = await omise.customers.create({
  email: 'subscriber@example.com',
  card: tokenId
});

// 月次請求（自動化）
setInterval(async () => {
  await omise.charges.create({
    customer: customer.id,
    amount: 99900,  // $9.99/月
    currency: 'usd',
    description: '月次サブスクリプション'
  });
}, 30 * 24 * 60 * 60 * 1000);  // 30日

後で使うためにカードを保存​

顧客がカードを保存し、後で購入を決定：

// チェックアウト: カードを保存
const customer = await omise.customers.create({
  email: 'shopper@example.com',
  card: tokenId,
  metadata: { loyalty_id: '12345' }
});

// 後で: クイックチェックアウト
const charge = await omise.charges.create({
  customer: customer.id,
  amount: 250000,
  currency: 'thb'
});

複数の支払い方法​

顧客が複数のカードを管理：

// 複数のカードを追加
await omise.customers.update(customerId, { card: token1 });
await omise.customers.update(customerId, { card: token2 });

// 顧客のカードを一覧
const customer = await omise.customers.retrieve(customerId);
console.log('カード:', customer.cards.data);

// 特定のカードに課金
await omise.charges.create({
  customer: customerId,
  card: customer.cards.data[1].id,  // 2番目のカード
  amount: 100000
});

顧客のライフサイクル​

ステート​

ステート説明課金可能？
アクティブ有効なカードを持つ顧客○ はい
カードなし支払い方法のない顧客× いいえ
削除済み顧客が削除済み× いいえ

カード管理​

  • カード追加: トークンを作成 → トークンで顧客を更新
  • デフォルト設定: default_cardパラメータで顧客を更新
  • カード削除: 顧客からカードを削除
  • カード更新: 有効期限、名前などを更新

セキュリティのベストプラクティス​

すべきこと​

  • カードを追加するにはトークンを使用（生のカードデータを送信しない）
  • データベースに顧客IDを保存
  • 課金を許可する前に顧客の所有権を確認
  • 内部追跡にはメタデータを使用
  • 顧客データを保護するために認証を実装
  • カードエラーを適切に処理（期限切れ、拒否）
  • 不要になった古い顧客を削除

すべきでないこと​

  • サーバーにカード番号を送信しない
  • 顧客IDを公開しない
  • 認証をスキップしない（ユーザーが顧客を所有していることを確認）
  • メタデータに機密データを保存しない
  • 許可なく課金しない（PCI要件）
  • 非アクティブな顧客を無期限に保持しない

データプライバシー​

GDPRコンプライアンス​

  • 要求に応じて顧客を削除
  • 要求に応じて顧客データをエクスポート
  • 最小限のメタデータを使用（必要なもののみ）
  • 顧客IDを保護（URLに公開しない）

PCIコンプライアンス​

  • 生のカード番号を決して保存しない
  • すべてのカード操作にトークンを使用
  • 顧客データへのアクセスを制限
  • 顧客データアクセスを監査

テスト​

テスト顧客​

テストトークンでテスト顧客を作成：

// テストモードの顧客
const customer = await omise.customers.create({
  email: 'test@example.com',
  card: 'tokn_test_no1t4tnemucod0e51mo'
});

// 顧客IDはcust_test_で始まる
console.log(customer.id);  // cust_test_...

テストカード​

テストカード番号を使用：

  • 4242424242424242 - Visa（成功）
  • 4000000000000002 - Visa（拒否）
  • 5555555555554444 - Mastercard（成功）

エラー処理​

一般的な顧客エラー：

エラーコード説明解決策
used_tokenトークンがすでに使用済み新しいトークンを作成
invalid_cardカードが無効カード詳細を検証
customer_not_found顧客IDが存在しない顧客IDを確認
card_not_foundカードが顧客に属していないカードIDを確認

APIリファレンス​

関連リソース​

統合ガイド​

ヘルプが必要ですか？ 顧客管理ガイドをご覧になるか、support@omise.coまでお問い合わせください。