メインコンテンツへスキップ

Omiseの仕組み

Omiseのコアコンセプトを理解することで、セキュアで効率的な決済統合を構築できます。token、charge、source、決済フローについて学びます。

概要​

Omiseは、企業が機密性の高いカードデータを直接扱うことなく、セキュアに決済を受け付けることができるPCI認証済み決済ゲートウェイです。tokenベースのアーキテクチャを使用することで、Omiseはカード情報をサーバーから除外し、セキュリティを維持しながらPCI準拠の負担を軽減します。

コアコンセプト​

1. Payment Gateway アーキテクチャ​

Omiseはアプリケーションと決済プロセッサーの間に位置し、以下を処理します:

  • Tokenization: 機密データをセキュアなtokenに変換
  • Authorization: 決済の検証と承認
  • Settlement: 顧客からアカウントへの資金移動
  • Reconciliation: すべての取引の追跡とレポート

2. 2サーバーモデル​

Omiseはセキュリティのために2つの独立したAPIエンドポイントを使用します:

Vault Server (vault.omise.co)​

  • 用途: 機密性の高いカード会員データを処理
  • 使用する鍵: Public key
  • 操作: tokenとsourceの作成
  • セキュリティ: カードデータをメインAPIから隔離

API Server (api.omise.co)​

  • 用途: その他すべての操作を処理
  • 使用する鍵: Secret key
  • 操作: charge、refund、transferなどの作成
  • セキュリティ: 生のカードデータを受信しない
なぜ2つのサーバー?

この分離により、機密性の高いカードデータがサーバーやメインAPIに触れることがないため、PCI準拠の要件が大幅に軽減されます。

3. API Key​

Omiseは3種類のAPI keyを使用します:

Keyタイプ形式使用用途クライアント側で安全?
Public Keypkey_test_...Tokenization✅ はい
Secret Keyskey_test_...すべての操作❌ いいえ(サーバーのみ)
Chain Keyck_test_...サブマーチャント❌ いいえ(サーバーのみ)

認証について詳しく見る →

4. 決済オブジェクト​

Token​

Tokenは決済方法(通常はカード)を表し、chargeの作成に一度だけ使用できます。

特性:

  • 単一使用のみ
  • 作成後30分間有効
  • tokenizeされたカード情報を含む
  • Public keyで作成

例:

{
  "object": "token",
  "id": "tokn_test_5xp6ca4dtzx5cskm9mk",
  "used": false,
  "card": {
    "brand": "Visa",
    "last_digits": "4242",
    "expiration_month": 12,
    "expiration_year": 2027
  }
}

Charge​

Chargeは顧客の決済方法への支払いリクエストを表します。

特性:

  • Token、source、またはcustomerカードで作成
  • 承認(後でキャプチャ)または即座にキャプチャ可能
  • カスタム追跡用のmetadataをサポート
  • 成功時にtransactionを生成

例:

{
  "object": "charge",
  "id": "chrg_test_5xp6ccfmecft4zxrb7p",
  "amount": 100000,
  "currency": "thb",
  "status": "successful",
  "paid": true,
  "authorized": true,
  "captured": true
}

Chargeステータス:

  • pending - 決済待ち(非同期決済方法の場合)
  • successful - 決済完了
  • failed - 決済拒否または失敗
  • expired - 決済期限切れ(非同期決済方法)

Source​

Sourceは、PromptPay、モバイルバンキング、QRコードなどの代替決済方法を表します。

特性:

  • 特定の決済方法用に作成
  • 単一使用または再利用可能
  • 多くの場合、決済指示が含まれる(QRコード、銀行詳細)
  • 完了するために顧客のアクションが必要

例:

{
  "object": "source",
  "id": "src_test_5xp6ccfmecft4zxrb7p",
  "type": "promptpay",
  "flow": "redirect",
  "amount": 100000,
  "currency": "thb",
  "scannable_code": {
    "image": {
      "download_uri": "https://...",
      "type": "qr_code"
    }
  }
}

Customer​

Customerオブジェクトは、継続的なchargeのための決済方法を保存します。

特性:

  • 複数のカードを保存可能
  • サブスクリプション課金を有効化
  • カスタム追跡用のmetadataをサポート
  • customerに紐付けられたカードは繰り返しchargeが可能

例:

{
  "object": "customer",
  "id": "cust_test_5xp6ccfmecft4zxrb7p",
  "email": "customer@example.com",
  "description": "John Doe",
  "cards": {
    "total": 1,
    "data": [...]
  }
}

決済フロー​

標準的なカード決済フロー​

典型的なカード決済の仕組み:

ステップバイステップ:

  1. 顧客がカード情報を入力します(チェックアウトページで)
  2. ブラウザがカードデータを送信します(Omise Vaultに、public keyを使用)
  3. Omiseがtokenを返します(カードを表す)
  4. ブラウザがtokenを送信します(サーバーに、カードデータではなく!)
  5. サーバーがchargeを作成します(secret key + tokenを使用)
  6. Omiseが決済を処理します(銀行と)
  7. 銀行が承認(または拒否)します
  8. Omiseが結果を返します(サーバーに)
  9. サーバーが注文を更新し、確認を表示します

代替決済方法フロー​

PromptPayやモバイルバンキングなどの場合:

主な違い:

  • Tokenの代わりにsourceを作成
  • 顧客がアプリ外で決済を完了
  • 決済完了時にwebhookを受信
  • 時間内に完了しない場合、決済が期限切れになる可能性

データフローとセキュリティ​

セキュアに保たれるもの​

セキュリティ原則:

  • ✅ カードデータはOmise Vaultに直接送信(サーバーには送信しない)
  • ✅ Tokenは単一使用で時間制限付き
  • ✅ Secret keyはサーバーに保持
  • ✅ すべての通信はHTTPS経由
  • ✅ PCI準拠のインフラストラクチャ

保存すべきもの​

保存すべきもの:

  • ✅ Charge ID
  • ✅ Customer ID
  • ✅ 注文情報
  • ✅ Metadata
  • ❌ カード番号
  • ❌ CVVコード
  • ❌ 完全なカード詳細

環境​

Test Mode​

  • シミュレートされたトランザクション
  • 実際のお金なし
  • テストカードと決済方法
  • 独立したダッシュボード
  • _test_プレフィックス付きのAPI key

Live Mode​

  • 実際のトランザクション
  • 実際のお金が処理される
  • 実際のカードと決済方法
  • 本番ダッシュボード
  • _test_プレフィックスなしのAPI key

Test vs Live Modeについて学ぶ →

資金の流れ​

決済プロセス​

保留期間:

  • タイ: 7日
  • 日本: 21日
  • シンガポール: 7日
  • マレーシア: 7日
  • Test Mode: 即時(テスト用)
注記

保留期間は、マーチャント契約とアカウント履歴によって異なる場合があります。特定の決済スケジュールについては、ダッシュボードを確認するか、サポートにお問い合わせください。

なぜ保留期間があるのか?

  • チャージバックからの保護
  • refundの処理時間
  • 業界標準の慣行

手数料​

Omiseは成功したトランザクションに手数料を請求します:

  • Charge金額から差し引かれます
  • 決済方法によって異なります
  • ダッシュボードとAPIで表示されます
  • セットアップ料金や月額料金はありません

高度なコンセプト​

事前承認(Auth & Capture)​

今すぐ決済を承認し、後でキャプチャ:

// ステップ1: 承認のみ
omise.charges.create({
  amount: 100000,
  currency: 'thb',
  card: token,
  capture: false  // まだキャプチャしない
});

// ステップ2: 後でキャプチャ(7日以内)
omise.charges.capture('chrg_test_123');

使用例:

  • ホテル予約
  • レンタカー
  • カスタム配送料金計算

3D Secure認証​

カードの追加セキュリティレイヤー:

  • 顧客が銀行で認証
  • 不正行為とチャージバックを削減
  • 一部のカードタイプで必須
  • 発行者への責任移転

3D Secureについて学ぶ →

Webhook​

イベントのリアルタイム通知:

  • Charge完了
  • Charge失敗
  • Refund作成
  • Transfer完了

Webhookを設定する →

一般的なパターン​

1回限りの決済​

// 1. Tokenを作成(クライアント側)
Omise.createToken('card', cardData, (status, response) => {
  // 2. Tokenをサーバーに送信
  fetch('/charge', {
    method: 'POST',
    body: JSON.stringify({ token: response.id })
  });
});

// 3. Chargeを作成(サーバー側)
omise.charges.create({
  amount: 100000,
  currency: 'thb',
  card: req.body.token
});

継続的な決済​

// 1. カード付きでcustomerを作成
const customer = await omise.customers.create({
  email: 'customer@example.com',
  card: token
});

// 2. 後でcustomerにcharge(tokenは不要)
await omise.charges.create({
  amount: 100000,
  currency: 'thb',
  customer: customer.id
});

代替決済方法​

// 1. Sourceを作成
const source = await omise.sources.create({
  type: 'promptpay',
  amount: 100000,
  currency: 'thb'
});

// 2. 顧客にQRコードを表示
displayQR(source.scannable_code.image.download_uri);

// 3. Webhook通知を待つ
// 顧客が支払うとwebhookが発火します

FAQ​

TokenとChargeの違いは何ですか?

Tokenは決済方法(カードなど)のセキュアな表現です。クライアント側で作成され、サーバーに送信されます。

Chargeは実際の支払いリクエストです。tokenを使用してサーバー上で作成され、顧客からあなたへのお金を処理します。

考え方: Token = 決済方法、Charge = 支払いリクエスト

なぜtokenを複数回使用できないのですか?

Tokenはセキュリティ上の理由から単一使用です。tokenが再利用できる場合、侵害されたtokenが複数の不正なchargeにつながる可能性があります。

継続的な決済の場合は、Customerオブジェクトを作成し、カードをそれに紐付けます。その後、新しいtokenを作成せずに、customerに複数回chargeできます。

Chargeが失敗するとどうなりますか?

失敗したchargeは、決済が失敗した理由の詳細を含むエラーを返します:

  • 残高不足
  • 無効なカード番号
  • 発行者によるカード拒否
  • 期限切れのカード

Chargeオブジェクトにはstatus: "failed"があり、理由を説明するfailure_codeとfailure_messageが含まれます。

非同期決済が完了したことをどのように知ることができますか?

代替決済方法(PromptPay、モバイルバンキングなど)の場合、webhookを使用して決済完了時に通知を受け取ります。

サーバー上でwebhookエンドポイントを設定し、Omiseダッシュボードで設定します。決済ステータスが変更されると、OmiseがエンドポイントにイベントデータをPOSTします。

Webhookについて学ぶ →

事前承認されたchargeを部分的にキャプチャできますか?

はい! 承認された金額より少ない金額をキャプチャできます:

// ฿1,000を承認
omise.charges.create({
  amount: 100000,
  currency: 'thb',
  card: token,
  capture: false
});

// ฿500のみキャプチャ
omise.charges.capture('chrg_123', {
  capture_amount: 50000
});

キャプチャされなかった金額は自動的に解放されます。

SourceとTokenの違いは何ですか?
  • Token: カード決済に使用、クライアント側で作成、単一使用
  • Source: 代替決済方法(PromptPay、QR、バンキング)に使用、決済指示を含む場合があり、顧客のアクションが必要な場合があります

どちらも決済方法を表しますが、sourceはより複雑な決済フローを処理します。

ビジュアルサマリー​

完全な決済エコシステム​

関連リソース​

構築の準備はできましたか? クイックスタートガイドから始めるか、すべての決済方法を探索してください。