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 Key	`pkey_test_...`	Tokenization	✅ はい
Secret Key	`skey_test_...`	すべての操作	❌ いいえ(サーバーのみ)
Chain Key	`ck_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": [...]
  }
}

決済フロー

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

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

ステップバイステップ:

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

代替決済方法フロー

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はより複雑な決済フローを処理します。

Omiseの仕組み

概要

コアコンセプト

1. Payment Gateway アーキテクチャ

2. 2サーバーモデル

Vault Server (`vault.omise.co`)

API Server (`api.omise.co`)

3. API Key

4. 決済オブジェクト

Token

Charge

Source

Customer

決済フロー

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

代替決済方法フロー

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

セキュアに保たれるもの

保存すべきもの

環境

Test Mode

Live Mode

資金の流れ

決済プロセス

手数料

高度なコンセプト

事前承認(Auth & Capture)

3D Secure認証

Webhook

一般的なパターン

1回限りの決済

継続的な決済

代替決済方法

FAQ

ビジュアルサマリー

完全な決済エコシステム

関連リソース

概要​

コアコンセプト​

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

2. 2サーバーモデル​

Vault Server (vault.omise.co)​

API Server (api.omise.co)​

3. API Key​

4. 決済オブジェクト​

Token​

Charge​

Source​

Customer​

決済フロー​

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

代替決済方法フロー​

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

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

保存すべきもの​

環境​

Test Mode​

Live Mode​

資金の流れ​

決済プロセス​

手数料​

高度なコンセプト​

事前承認(Auth & Capture)​

3D Secure認証​

Webhook​

一般的なパターン​

1回限りの決済​

継続的な決済​

代替決済方法​

FAQ​

ビジュアルサマリー​

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

関連リソース​

概要

コアコンセプト

1. Payment Gateway アーキテクチャ

2. 2サーバーモデル

Vault Server (`vault.omise.co`)

API Server (`api.omise.co`)

3. API Key

4. 決済オブジェクト

Token

Charge

Source

Customer

決済フロー

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

代替決済方法フロー

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

セキュアに保たれるもの

保存すべきもの

環境

Test Mode

Live Mode

資金の流れ

決済プロセス

手数料

高度なコンセプト

事前承認(Auth & Capture)

3D Secure認証

Webhook

一般的なパターン

1回限りの決済

継続的な決済

代替決済方法

FAQ

ビジュアルサマリー

完全な決済エコシステム

関連リソース