OnePayOnePay

API ドキュメント

Payment System API とのシステム連携

請求書の作成、決済リンクの共有、顧客管理をプログラムから行えます。MCP 経由で AI アシスタントに任せることも可能です。どちらのインターフェースも同じバリデーション・権限・マーチャントスコープを共有します。

適切な API インターフェースを選ぶ

  • マーチャント・管理者 API — マーチャントアカウント、請求書、顧客、カタログデータ向けの認証済みツールです。
  • 公開 Shared Events REST API

クイックスタート

  1. API トークンページ(プロフィール → API トークン)で API トークンを作成
  2. 下記のベース URL をコピー
  3. 最初のリクエストを送信
リクエスト例
curl https://admin.onepay.tabsystems.tech/api/v1/invoices \
  -H "Authorization: Bearer psk_your_token_here"

認証

すべてのリクエストに API トークンを含む Authorization ヘッダーが必要です。トークンは API トークンページ(プロフィール → API トークン)で失効・無効化できます。

トークンは作成したユーザーのロールを引き継ぎます。プロフィールページで失効や有効期限の設定ができ、失効は REST・MCP の両方に即時反映されます。

ベース URL: https://admin.onepay.tabsystems.tech/api/v1
Authorization: Bearer psk_your_token_here

エラー

400バリデーション失敗:body/query がスキーマと一致しません。`issues` に Zod のエラー内容が入ります
401API トークンが未指定、無効、期限切れ、または失効しています
403トークンにこの操作の権限がありません
422ドメインルール違反(invalidAmount、noPaymentProvider など)

Webhook

API トークンページ(プロフィール → API トークン)で API トークンに Webhook URL を設定すると、そのトークンで作成した請求書が以下のように変化したときにイベントを POST します。請求書には作成時に送信した externalReference と metadata が含まれます(metadata は UTF-8 の JSON で 8 KB まで。超える場合は 400 で拒否されます)。トークンを失効しても、作成済みの請求書のイベントは停止しません。

invoice.paid請求書が支払済み(captured)になりました。
invoice.expired請求書が期限切れになりました。
invoice.cancelled請求書がキャンセルされました。
webhook.testAPI トークンページで「テストイベントを送信」を押したときだけ送信されます。data には apiTokenId と message が入り、請求書はありません。他のイベントと同じく署名され、1 回だけ送信されて再試行はされません。2xx で応答してください。それ以外の処理は不要です。
リクエストボディ
{
  "id": "evt_5f0c2b7a9d1e4c3b8a6f2e10",
  "type": "invoice.paid",
  "createdAt": "2026-10-06T03:15:07.120Z",
  "data": {
    "invoice": {
      "id": "cmg1x2y3z0000abcd1234efgh",
      "status": "captured",
      "title": "Order 1042",
      "amount": 110000,
      "taxAmount": 10000,
      "currency": "MNT",
      "externalReference": "order-1042",
      "metadata": { "cartId": "c-77" },
      "paidAt": "2026-10-06T03:15:05.000Z",
      "expiresAt": "2026-10-07T00:00:00.000Z",
      "createdAt": "2026-10-06T02:58:41.000Z"
    }
  }
}

署名の検証

すべてのリクエストには x-onepay-timestamp(Unix 秒)と x-onepay-signature が付きます。署名は Webhook の whsec_ シークレット(API トークンではありません)をキーとした timestamp + "." + raw body の HMAC-SHA256(16 進)です。生のボディで再計算し、定数時間で比較し、古いタイムスタンプは拒否してください。

Node.js での検証
import { createHmac, timingSafeEqual } from 'node:crypto'

const TOLERANCE_SECONDS = 300

// rawBody: the request body exactly as received (a string), before any JSON parsing.
// secret: the whsec_… value shown when you set the webhook URL — not your API token.
export const verifyOnePayWebhook = (rawBody, headers, secret) => {
  const timestamp = headers['x-onepay-timestamp']
  const signature = headers['x-onepay-signature']

  if (!timestamp || !signature) return false

  // Refuse old deliveries so a captured request cannot be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false

  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')

  return expected.length === signature.length
    && timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

10 秒以内に 2xx を返してください。それ以外(リダイレクトを含む)は失敗とみなし、1 分、5 分、30 分、2 時間、12 時間後に再試行した後に中止します。失敗した配信は、キーの Webhook ダイアログ(プロフィール → API トークン)の直近の配信から再送できます。同じイベントが複数回届くことがあるため、id(x-onepay-event-id にも含まれます)で重複を排除してください。

キーをローテーションすると、Webhook の URL・シークレット・有効設定が新しいキーにコピーされます。請求書は作成したキーに紐づいたままです。旧キーで作成した請求書は、ローテーション時点でコピーされた旧キーの Webhook 設定を使い続け、その後に新キーの Webhook を変更しても影響を受けません(旧キーの Webhook も同じページで編集できます)。

管理画面を使わず、そのキー自身で Webhook を管理することもできます:GET/PUT/DELETE /api/v1/webhook、POST /api/v1/webhook/secret(シークレットのローテーションを要求)、POST /api/v1/webhook/test、GET /api/v1/webhook/deliveries(直近 5 件、接続確認用)、または MCP ツール get_webhook、set_webhook、rotate_webhook_secret、send_test_webhook、list_webhook_deliveries、delete_webhook。いずれもリクエストを認証したキー自身の Webhook のみを対象とし、https と公開アドレスの検証は管理画面と同じで、シークレットは set_webhook で初めて作成したときにのみ返されます。この方法で要求したローテーションはすぐには適用されません。キーの所有者にメールが届き、30 分以内に API トークンページで承認または却下します。新しいシークレットは管理画面でのみ表示されるため、漏えいしたキーだけではシークレットを差し替えられません。変更は API トークンページにすぐ反映されます。

ダウンロード

API リファレンスMCP 接続ガイド
© 2025–2026 Tab Systems Mongolia LLC