バージョン: 最新版

Omise APIリファレンス

Omise RESTful APIで強力な決済連携を構築しましょう。東南アジアと日本で40以上の決済方法に対応した決済処理が可能です。

概要

Omise APIはREST原則に基づいて設計されており、予測可能なリソース指向のURL、JSONエンコードのリクエストとレスポンス、標準的なHTTPレスポンスコードとHTTPメソッドを使用します。

ベースURL

サーバー	URL	用途
APIサーバー	`https://api.omise.co`	課金、顧客、振込、アカウント操作
Vaultサーバー	`https://vault.omise.co`	トークン作成（安全なカードデータ処理）

現在のAPIバージョン

バージョン: 2019-05-29

Omise-Versionヘッダーを使用してAPIバージョンを指定します（オプション、デフォルトはアカウントのAPIバージョン）:

Omise-Version: 2019-05-29

クイックスタート

1. APIキーを取得する

OmiseダッシュボードでAPIキーを確認できます:

公開キー (pkey_*) - クライアントサイド操作用（トークン、ソース）
秘密キー (skey_*) - サーバーサイド操作用（課金、顧客）

秘密キーを安全に保管してください

秘密キーをクライアントサイドコード、GitHubリポジトリ、または公開場所に公開しないでください。環境変数とサーバーサイドコードのみを使用してください。

2. リクエストを認証する

OmiseはHTTP Basic認証を使用します:

ユーザー名: APIキー
パスワード: 空白（空文字列）

# 秘密キーを使用
curl https://api.omise.co/charges \
  -u skey_test_YOUR_SECRET_KEY:

# 公開キーを使用
curl https://vault.omise.co/tokens \
  -u pkey_test_YOUR_PUBLIC_KEY:

3. 最初のリクエストを送信する

テスト課金を作成します:

curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_YOUR_SECRET_KEY: \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "card=tokn_test_no1t4tnemucod0e51mo"

レスポンス:

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

APIリソース

コア決済処理

💳 課金

すべての対応決済方法で課金の作成、キャプチャ、管理を行います。

POST /charges • GET /charges/:id • PATCH /charges/:id

🔐 トークン

PCI準拠の負担なくクレジットカード情報を安全にトークン化します。

POST /tokens • GET /tokens/:id

📱 ソース

PromptPay、モバイルバンキング、QRコードなどの代替決済方法用の決済ソースを作成します。

POST /sources • GET /sources/:id

↩️ 返金

完了した課金に対して全額または部分返金を発行します。

POST /charges/:id/refunds • GET /refunds/:id

顧客管理

👤 顧客

継続課金のために顧客情報と保存された決済方法を管理します。

POST /customers • GET /customers/:id • PATCH /customers/:id

💳 カード

顧客に紐付けられた保存済みクレジット/デビットカードを管理します。

GET /customers/:id/cards • DELETE /customers/:id/cards/:card_id

資金管理

💸 振込

銀行口座への資金振込と自動振込スケジュールを管理します。

POST /transfers • GET /transfers/:id • GET /transfers/schedules

🏦 受取人

振込用の銀行口座受取人を作成・検証します。

POST /recipients • GET /recipients/:id • POST /recipients/:id/verify

💰 残高

すべての通貨で利用可能残高と保留中残高を確認します。

GET /balance

📊 取引

会計と照合のための詳細な取引履歴を表示します。

GET /transactions • GET /transactions/:id

追加リソース

⚖️ 異議申し立て

チャージバックと異議申し立てを管理します。

📢 イベント

Webhook用のイベントログにアクセスします。

📅 スケジュール

継続課金と振込を設定します。

🔗 決済リンク

共有可能な決済リンクを作成します。

🔍 検索

すべてのリソースを横断検索します。

⚙️ アカウント

アカウント設定を表示・更新します。

必須ガイド

特定のエンドポイントに進む前に、以下のコアコンセプトを理解しておきましょう:

🔐 認証

公開キーと秘密キーを使用したAPIリクエストの認証方法、APIバージョニングの処理、連携のセキュリティ確保について学びます。

❌ エラー処理

エラーレスポンスの形式、一般的なエラーコード、失敗を適切に処理するためのベストプラクティスを理解します。

📄 ページネーション

オフセットとリミットパラメータを使用して大規模な結果セットを効率的にナビゲートします。

🔁 べき等性

べき等キーを使用して、操作を重複させることなく安全にリクエストを再試行します。

🏷️ APIバージョニング

APIバージョンの変更を管理し、下位互換性を維持します。

⏱️ レート制限

APIレート制限内に収まり、レート制限エラーを処理します。

一般的なワークフロー

クレジットカード決済を受け付ける

クライアントサイド: カードデータでトークンを作成
```
POST https://vault.omise.co/tokens
```
サーバーサイド: トークンで課金を作成
```
POST https://api.omise.co/charges
```

完全ガイドを見る →

PromptPay QR決済を受け付ける

サーバーサイド: PromptPayソースを作成
```
POST https://api.omise.co/sources
```
顧客にQRコードを表示
決済完了時にWebhookを受信

完全ガイドを見る →

将来の課金用にカードを保存する

顧客を作成
```
POST https://api.omise.co/customers
```
顧客にカードトークンを紐付け
```
PATCH https://api.omise.co/customers/:id
```
顧客のデフォルトカードに課金
```
POST https://api.omise.co/charges
```

完全ガイドを見る →

レスポンス形式

すべてのAPIレスポンスは、リソースタイプを示すobjectフィールドを持つJSONエンコードされたオブジェクトです:

{
  "object": "charge",
  "id": "chrg_test_5xuy4w91xqz7d1w9u0t",
  "livemode": false,
  "amount": 100000,
  "currency": "thb",
  ...
}

リストオブジェクト

リストエンドポイントはページネーションされた結果を返します:

{
  "object": "list",
  "data": [
    { "object": "charge", "id": "chrg_..." },
    { "object": "charge", "id": "chrg_..." }
  ],
  "limit": 20,
  "offset": 0,
  "total": 142,
  "from": "2025-01-01T00:00:00Z",
  "to": "2025-02-07T23:59:59Z"
}