Sources API
概要
Sources APIを使用すると、クレジットカード以外の代替決済手段を受け付けることができます。Sourceは、PromptPay QRコード、モバイルバンキング、インターネットバンキング、分割払いプランなどの決済チャネルを表します。
Sourceとは
Sourceは、以下を表す決済手段オブジェクトです。
- PromptPay QRコード - リアルタイムQRベースの決済
- モバイルバンキング - アプリ内決済リダイレクト（SCB Easy、Krungthai Nextなど）
- インターネットバンキング - オンライン銀行振込
- コンビニエンスストア - セブンイレブン、ファミリーマートなどでの現金決済
- 分割払いプラン - 分割払いオプション
- Eウォレット - TrueMoney、Rabbit LINE Payなど
主な機能
幅広い決済手段のサポート
- QR決済 - PromptPay、Alipay、WeChat Pay
- 銀行振込 - モバイルおよびインターネットバンキング
- 分割払い - 0%金利分割払いプラン
- 現金決済 - コンビニエンスストアでの決済
- Eウォレット - デジタルウォレット連携
柔軟なワークフロー
- リダイレクトベース - 顧客を決済完了のためにリダイレクト
- QRコード表示 - 顧客がスキャンするためのQRコードを表示
- Webhook通知 - リアルタイムの決済ステータス更新
- 非同期処理 - サイト外で完了する 決済
地域サポート
- タイ - PromptPay、SCB、Krungthai、BAY、BBLなど
- マレーシア - FPX、Boost、GrabPay、Touch 'n Go
- シンガポール - PayNow、GrabPay
- 国際 - Alipay、WeChat Pay
Sourceの仕組み
標準フロー
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Your │ │ Omise │ │ Payment │ │ Customer│
│ Server │ │ API │ │ Provider│ │ │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
│ │ │ │
│ 1. Create source │ │ │
├──────────────────>│ │ │
│ │ │ │
│ 2. Return source │ │ │
│ (with QR/URL) │ │ │
│<──────────────────┤ │ │
│ │ │ │
│ 3. Create charge │ │ │
├──────────────────>│ │ │
│ │ │ │
│ 4. Return charge │ │ │
│ (status:pending) │ │
│<──────────────────┤ │ │
│ │ │ │
│ 5. Display QR │ │ │
│ or redirect │ │ │
├──────────────────────────────────────────────────────────>│
│ │ │ │
│ │ │ 6. Customer pays │
│ │ │<──────────────────┤
│ │ │ │
│ │ 7. Webhook notify │ │
│<──────────────────┤ │ │
│ │ │ │
│ 8. Show success │ │ │
├──────────────────────────────────────────────────────────>│
│ │ │ │
実装手順
- Sourceの作成 - 決済手段タイプと金額を指定
- Chargeの作成 - Source IDを使用してChargeを作成（ステータス: pending）
- 決済UIの表示 - QRコードを表示するか、顧客をリダイレクト
- Webhookの待機 - 顧客が非同期で決済を完了
- ステータスの確認 - WebhookまたはAPI経由でChargeステータスを確認
- 注文の処理 - 決済成功後に注文を処理
Sourceタイプ
QRベースの決済
| Type | Description | Region |
|---|---|---|
| promptpay | タイの国民的QR決済 | Thailand |
| alipay | 中国の主要Eウォレット | International |
| wechat_pay | WeChat Pay QR | International |
| paynow | シンガポールのQR決済 | Singapore |
モバイルバンキング
| Type | Description | Region |
|---|---|---|
| mobile_banking_scb | SCB Easyアプリ | Thailand |
| mobile_banking_kbank | K PLUSアプリ | Thailand |
| mobile_banking_bbl | Bangkok Bank Mobile | Thailand |
| mobile_banking_bay | Krungsri Mobile | Thailand |
| mobile_banking_ktb | Krungthai NEXTアプリ | Thailand |
インタ ーネットバンキング
| Type | Description | Region |
|---|---|---|
| internet_banking_scb | SCBオンラインバンキング | Thailand |
| internet_banking_bbl | Bangkok Bankオンライン | Thailand |
| internet_banking_bay | Krungsriオンライン | Thailand |
| fpx | マレーシアのオンラインバンキング | Malaysia |
その他の決済手段
| Type | Description | Region |
|---|---|---|
| truemoney | TrueMoney Wallet | Thailand |
| rabbit_linepay | Rabbit LINE Pay | Thailand |
| installment_bay | Krungsri分割払い | Thailand |
| installment_kbank | Kasikornbank分割払い | Thailand |
| econtext | コンビニエンスストア決済 | Japan |
Sourceのライフサイクル
状態
| State | Description | Charge Status |
|---|---|---|
| pending | Source作成済み、決済待ち | pending |
| successful | 決済完了 | successful |
| failed | 決済失敗または拒否 | failed |
| expired | 決済期間が期限切れ | expired |
有効期限ルール
決済手段によってデフォルトの有効期限が異なります。
有効期限の確認
以下に記載されている有効期限は、入手可能なドキュメントに基づいており、変更される場合があります。特定の決済手段の最も正確で最新の有効期限については、個々の決済手段のドキュメントを参照するか、Omiseサポートにお問い合わせください。
| Payment Method | Default Expiration | Custom Expiration |
|---|---|---|
| PromptPay | 24時間 | expires_inでカスタマイズ可能 |
| Mobile Banking (SCB/KBANK/BBL/BAY/KTB) | 15-30分* | expires_in でカスタマイズ可能 |
| Internet Banking (SCB/BBL/BAY) | 15-30分* | expires_inでカスタマイズ可能 |
| FPX (Malaysia) | 30分* | expires_inでカスタマイズ可能 |
| PayNow (Singapore) | 15-30分* | expires_inでカスタマイズ可能 |
| Alipay | 15-30分* | expires_inでカスタマイズ可能 |
| WeChat Pay | 15-30分* | expires_inでカスタマイズ可能 |
| TrueMoney Wallet | 15-30分* | expires_inでカスタマイズ可能 |
| Rabbit LINE Pay | 15-30分* | expires_inでカスタマイズ可能 |
| GrabPay | 15-30分* | expires_inでカスタマイズ可能 |
| Boost | 15-30分* | expires_inでカスタマイズ可能 |
| Touch 'n Go | 15-30分* | expires_inでカスタマイズ可能 |
| Installment Plans (BAY/KBANK) | 24-48時間* | expires_inでカスタマイズ可能 |
| Convenience Stores (Japan) | 7日間* | expires_inでカスタマイズ可能 |
*正確な値については、特定の決済手段のドキュメントまたはOmiseサポートでご確認ください。
カスタム有効期限の設定：
const source = await omise.sources.create({
type: 'promptpay',
amount: 100000,
currency: 'thb',
expires_in: 1800 // 30 minutes (in seconds)
});
ベストプラクティス:
- 推奨される有効期限については、個々の決済手段のドキュメントを確認してください
- QR決済の場合は短い有効期限（5-15分）を設定して、古いQRコードを防止します
- 銀行振込の場合は長い有効期限（24-48時間）を設定して、処理時間を確保します
- 注文ステータスを更新するため、常に
source.expiredWebhookイベントを処理してください
APIエンドポイント
| Method | Endpoint | Description |
|---|---|---|
| POST | /sources | 新しいSourceを作成 |
| GET | /sources/:id | Source情報を取得 |
クイックスタート
PromptPay QR決済の例
// 1. PromptPay Sourceを作成
const source = await omise.sources.create({
type: 'promptpay',
amount: 100000,
currency: 'thb'
});
// 2. SourceでChargeを作成
const charge = await omise.charges.create({
amount: 100000,
currency: 'thb',
source: source.id,
return_uri: 'https://example.com/payment/complete'
});
// 3. QRコードを顧客に表示
const qrCodeUrl = charge.source.scannable_code.image.download_uri;
console.log('Show QR code:', qrCodeUrl);
// 4. Webhook通知を待つ
// Webhookイベント: charge.complete
// Chargeステータスが「successful」に変更されたことを確認
モバイルバンキングの例
// 1. モバイルバンキングSourceを作成
const source = await omise.sources.create({
type: 'mobile_banking_scb',
amount: 50000,
currency: 'thb'
});
// 2. Chargeを作成
const charge = await omise.charges.create({
amount: 50000,
currency: 'thb',
source: source.id,
return_uri: 'https://example.com/payment/complete'
});
// 3. 顧客をauthorize_uriにリダイレクト
const redirectUrl = charge.authorize_uri;
// 顧客をこのURLにリダイレクト
window.location.href = redirectUrl;
// 4. 顧客がバンキングアプリで決済を完了
// 5. 顧客がreturn_uriにリダイレクトされる
// 6. 決済完了時にWebhookが送信される
決済フロー
QRコードフロー（PromptPay、Alipay、WeChat Pay）
- Sourceを作成 → Chargeを作成
- QRコードを顧客に表示
- 顧客がモバイルアプリでスキャン
- 顧客がアプリで決済を確認
- Webhook通知が送信される
- 注文ステータスを更新
リダイレクトフロー（モバイルバンキング、インターネットバンキング）
- Sourceを作成 → Chargeを作成
- 顧客を
authorize_uriにリダイレクト - 顧客が決済を完了
- 顧客が
return_uriにリダイレクトされる - Webhook通知が送信される
- 決済ステータスを確認
オフラインフロー（コ ンビニエンスストア）
- Sourceを作成 → Chargeを作成
- 決済コードを顧客に表示
- 顧客がコンビニエンスストアで支払う
- Webhook通知が送信される（数時間/数日後）
- 注文を処理
一般的な使用例
単一決済
const source = await omise.sources.create({ type: 'promptpay', amount: 100000, currency: 'thb' });
const charge = await omise.charges.create({ amount: 100000, currency: 'thb', source: source.id });
分割払い
const source = await omise.sources.create({
type: 'installment_kbank',
amount: 300000,
currency: 'thb',
installment_term: 6 // 6か月
});
const charge = await omise.charges.create({ amount: 300000, currency: 'thb', source: source.id });
コンビニエンスストア決済
const source = await omise.sources.create({
type: 'econtext',
amount: 50000,
currency: 'jpy',
name: 'TARO YAMADA',
email: 'taro@example.com',
phone_number: '+81312345678'
});
const charge = await omise.charges.create({ amount: 50000, currency: 'jpy', source: source.id });
ベストプラクティス
✅ 推奨事項
- return_uriを設定 リダイレクトベースの決済の場合
- Webhookを実装 非同期通知用
- 明確な指示を表示 各決済手段に対して
- 適切な有効期限を設定 決済タイプに基づいて
- 決済ステータスを確認 ポーリングではなくWebhook経由で
- タイムアウトを適切に処理 （顧客が完了しなかった場合）
- 各決済手段をテスト 本番環境に移行する前に
- Source IDを保存 追跡とサポートのため
❌ 非推奨事項
- 頻繁にポーリングしない （Webhookを使用）
- 即時決済を想定しない （非同期です）
- return_uriをスキップしない （顧客は戻る必要があります）
- 有効期限を無視しない （Sourceは期限切れになります）
- 決済手段を混在させない （1つのSource = 1つの決済タイプ）
- 誤った通貨でSourceを使用しない （タイプ固有）
セキュリティに関する考慮事項
Webhook検証
常にWebhook署名を検証して、真正性を確認してください。
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const hmac = crypto.createHmac('sha256', secret);
hmac.update(payload);
const expectedSignature = hmac.digest('hex');
return signature === expectedSignature;
}
ステータス検証
return_uriパラメータだけを信頼しないでください。常にChargeステータスを確認してください。
// 顧客が決済から戻る
app.get('/payment/complete', async (req, res) => {
const chargeId = req.query.charge_id;
// 実際のChargeステータスを確認
const charge = await omise.charges.retrieve(chargeId);
if (charge.status === 'successful') {
// 決済確認済み、注文を処理
} else {
// 決済未完了、エラーを表示
}
});
テスト
テストモード
すべてのSourceタイプは、テストシークレットキーを使用してテストモードで動作します。
決済のシミュレーション
テストモードでは、以下が可能です。
- SourceとChargeの作成
- Webhookの受信
- リダイレクトフローのテスト
- テストQRコードの生成
テストWebhook
ローカル開発にはWebhookテストツールまたはngrokを使用してください。
ngrok http 3000
# OmiseダッシュボードでWebhook URLを設定
エラー処理
一般的なSourceエラー：
| Error Code | Description | Solution |
|---|---|---|
invalid_source_type | サポートされていない決済手段 | 通貨で利用可能なタイプを確認 |
amount_too_low | 最小金額を下回る | 決済タイプの最小金額を確認 |
currency_not_supported | 誤った通貨 | 決済タイプがサポートする通貨を確認 |
expired_source | Sourceが期限切れ | 新しいSourceを作成 |
APIリファレンス
関連リソース
決済手段ガイド
お困りですか？ 決済手段ガイドをご確認いただくか、support@omise.coまでお問い合わせください