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

Cards API

概要​

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

カードは顧客リソースです

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

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

すべてのカード操作はCustomers APIの下にあります：

できること​

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

カードの仕組み​

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

まず、public keyを使用してtokenを作成します（クライアント側）：

// 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) {
    // tokenをサーバーに送信
    sendTokenToServer(response.id);
  }
});

2. カードを顧客に添付​

次に、tokenを顧客に添付します（サーバー側）：

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

console.log('カードが追加されました:', customer.cards.data[0].id);

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

顧客のデフォルトカードをchargeします：

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_...'
});

Cardオブジェクトの構造​

{
  "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（public key）を使用
  • tokenまたはcard IDのみを保存
  • カード番号やCVVコードをログに記録しない
  • すべてのAPIリクエストでHTTPSを使用
  • クライアントで検証 - トークン化の前に

カードデータの保存​

顧客にカードを保存する場合：

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

使用例​

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

定期的なchargeのために顧客カードを保存：

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

// 毎月charge
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}（下4桁：${card.last_digits}）`);
});

// 選択されたカードをcharge
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を使用
  • デフォルトカードを設定 - chargeを簡単にするため
  • 有効期限を積極的に更新
  • 古いカードを削除 - プロファイルをクリーンに保つ
  • カードを検証 - 少額の承認chargeで
  • カード更新を適切に処理 - UIで適切に処理

❌ 避けるべき事項​

  • 生のカードデータを送信しない - サーバーに送信しない
  • CVVコードを保存しない - 違法かつ不要
  • 削除されたカードをchargeしない - まずカードが存在することを確認
  • 有効期限を無視しない - chargeの前に検証
  • 顧客間でカードを共有しない

関連リソース​

関連情報​

カードの管理を始める準備はできましたか？ カードの一覧表示から始めるか、顧客の作成について詳しく学んでください。