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

カードAPI

概要​

カードAPIを使用すると、顧客プロファイルに保存されたクレジット/デビットカードを管理できます。カードを保存するには、顧客に紐付ける必要があります。

カードは顧客リソース

Omise APIのカードは常に顧客に関連付けられています。カードを管理するには、顧客カードエンドポイントを使用してください。

利用可能なエンドポイント​

すべてのカード操作は顧客APIの下にあります:

できること​

  • カードを保存 - トークン化されたカードを顧客に紐付け
  • 顧客のカードを一覧表示 - 顧客のすべてのカードを表示
  • カード詳細を更新 - カードのメタデータを変更（名前、有効期限、請求先住所）
  • デフォルトカードを設定 - 課金に使用するカードを選択
  • カードを削除 - 顧客プロファイルからカードを削除
  • 複数のカードを管理 - 顧客ごとに複数の決済方法を保存

カードの仕組み​

1. カードデータをトークン化​

まず、公開キー（クライアントサイド）を使用してトークンを作成:

// Omise.jsを使用したクライアントサイド
Omise.setPublicKey('pkey_test_...');
Omise.createToken('card', {
  name: 'JOHN DOE',
  number: '4242424242424242',
  expiration_month: 12,
  expiration_year: 2025,
  security_code: '123'
}, (status, response) => {
  if (status === 200) {
    // トークンをサーバーに送信
    sendTokenToServer(response.id);
  }
});

2. 顧客にカードを紐付け​

次に、トークンを顧客に紐付け（サーバーサイド）:

// サーバーサイド
const customer = await omise.customers.update('cust_test_...', {
  card: 'tokn_test_...'
});

console.log('カード追加:', customer.cards.data[0].id);

3. 保存されたカードを使用​

顧客のデフォルトカードに課金:

const charge = await omise.charges.create({
  amount: 100000,
  currency: 'thb',
  customer: 'cust_test_...'
});

または特定のカードを指定:

const charge = await omise.charges.create({
  amount: 100000,
  currency: 'thb',
  customer: 'cust_test_...',
  card: 'card_test_...'
});

カードオブジェクトの構造​

{
  "object": "card",
  "id": "card_test_5xuy4w91xqz7d1w9u0t",
  "livemode": false,
  "location": "/customers/cust_test_.../cards/card_test_...",
  "country": "th",
  "city": "Bangkok",
  "postal_code": "10320",
  "financing": "",
  "bank": "Bank of Ayudhya",
  "brand": "Visa",
  "fingerprint": "XK2FJbz+kQFvd/kLLRm1BVXR1kbwJpQp+lkFZyqP0u8=",
  "last_digits": "4242",
  "name": "JOHN DOE",
  "expiration_month": 12,
  "expiration_year": 2025,
  "security_code_check": true,
  "created_at": "2025-02-07T00:00:00Z"
}

セキュリティとPCIコンプライアンス​

安全なプラクティス​

  • 生のカードデータをサーバーに送信しない
  • 常にトークン化（Omise.js（公開キー）を使用）
  • トークンまたはカードIDのみを保存
  • カード番号やCVVコードをログに記録しない
  • すべてのAPIリクエストにHTTPSを使用
  • トークン化前にクライアントで検証

カードデータの保存​

カードを顧客に保存すると:

  • ✅ Omiseが暗号化されたカードデータを保存
  • ✅ カードID（card_test_...）を受け取る
  • ✅ 下4桁、ブランド、有効期限を表示可能
  • ❌ 完全なカード番号は受け取れない
  • ❌ CVVは保存されない（課金には常に必要）

ユースケース​

サブスクリプションと継続課金​

継続課金のために顧客のカードを保存:

// カードを保存
const customer = await omise.customers.create({
  email: 'subscriber@example.com',
  card: 'tokn_test_...'
});

// 毎月課金
async function chargeMonthly() {
  const charge = await omise.charges.create({
    amount: 99900, // 999円のサブスクリプション
    currency: 'thb',
    customer: customer.id,
    description: '月額サブスクリプション'
  });
}

ワンクリック決済​

カード詳細を再入力せずに決済できるようにする:

// 顧客がチェックアウトで保存済みカードを選択
const cards = await omise.customers.listCards('cust_test_...');

// 顧客にカードを表示
cards.data.forEach(card => {
  console.log(`${card.brand}の末尾${card.last_digits}`);
});

// 選択されたカードに課金
const charge = await omise.charges.create({
  amount: 150000,
  currency: 'thb',
  customer: 'cust_test_...',
  card: selectedCardId
});

期限切れカードの更新​

カードの有効期限を更新:

const updatedCard = await omise.customers.updateCard(
  'cust_test_...',
  'card_test_...',
  {
    expiration_month: 12,
    expiration_year: 2026,
    name: 'JOHN DOE'
  }
);

ベストプラクティス​

すべきこと​

  • クライアントサイドでトークン化（Omise.jsを使用）
  • デフォルトカードを設定（課金を容易にするため）
  • 有効期限を事前に更新
  • 古いカードを削除（プロファイルを整理）
  • カードを検証（小額のオーソリ課金で）
  • カード更新を適切に処理（UIで）

すべきでないこと​

  • 生のカードデータをサーバーに送信しない
  • CVVコードを保存しない（違法で不要）
  • 削除されたカードに課金しない（カードの存在を先に確認）
  • 有効期限を無視しない（課金前に検証）
  • 顧客間でカードを共有しない

関連リソース​

参照​

カード管理を始める準備はできましたか？ カード一覧から始めるか、顧客の作成について学びましょう。