APIリファレンス

ベースURL

本番環境

https://cryptomerchant.online/api/v1https://cryptomerchant.online/api/v1

ローカル開発環境

http://localhost:3000/api/v1http://localhost:3000/api/v1

このAPIの機械可読な仕様は/openapi.json（OpenAPI 3.1）にあります。Postmanやクライアントジェネレーターにインポートできます。

認証

すべてのリクエストのAuthorizationヘッダーで、シークレットキーをBearerトークンとして送信します。キーは管理画面の開発者で作成します。

Authorization: Bearer cm_live_…

• キーは、メインネットではcm_live_、テストネットではcm_test_で始まります。
• キー全体は作成時に一度だけ表示されます。当社はキーのハッシュのみを保存するため、安全な場所に保管してください。
• キーはサーバー上でのみ使用してください。Webページ、モバイルアプリ、公開コードリポジトリには絶対に含めないでください。
• キーが漏洩したおそれがある場合は、管理画面で無効化し、新しいキーを作成してください。

エラー

リクエストが失敗した場合、レスポンスにはHTTPエラーステータスと、機械可読なcodeおよび人が読めるmessageを含むJSONボディが返されます：

{
  "error": {
    "code": "amount_too_small",
    "message": "Amount must be at least 0.50 USD."
  }
}

HTTPステータス

400

リクエストが無効です。たとえば、フィールドが不足している、または金額が小さすぎる場合です。

401

APIキーがない、誤っている、または無効化されています。

403

アカウントがこの操作を行えません。まだ有効化されていないか、停止されています。

404

オブジェクトが存在しないか、別のビジネスに属しています。

409

請求書の現在のステータスではこの操作を行えません。たとえば、すでに決済がある請求書をキャンセルしようとした場合です。

500

当社側で問題が発生しました。しばらくしてから再度お試しください。

表示される可能性のあるコード

invalid_json

リクエストボディがJSONオブジェクトではありません。

invalid_request

フィールドが不足しているか、無効です。メッセージに該当するフィールド名が示されます。

unauthorized

APIキーがない、誤っている、または無効化されています。

account_suspended

この加盟店アカウントは停止されています。

merchant_not_live

アカウントがまだ有効化されていません。先に管理画面で設定を完了してください。

invalid_amount

金額がない、数値ではない、または0より大きくありません。

amount_too_small

金額が0.50米ドル未満です。

invalid_asset

コインIDが既知のコインではありません。

asset_not_accepted

そのコインは受け付けていません。

invalid_state

請求書の現在のステータスではこの操作を行えません。

not_found

そのIDのオブジェクトは存在しません。

server_error

当社側で問題が発生しました。

請求書オブジェクト

請求書は、APIレスポンスとWebhookでこの形式になります。金額は精度が失われないよう、10進数の文字列で表されます。

idstring

請求書ID。inv_で始まります。

objectstring

常にinvoiceです。

statusstring

現在のステータス。以下のステータス一覧をご覧ください。

amountstring

請求した価格（currency建て）。

currencystring

価格の通貨。例：USD。

amount_usdstring

米ドル建ての価格。

descriptionstring | null

顧客に表示される説明。

order_idstring | null

自社の注文参照番号。

customer_emailstring | null

顧客のメールアドレス（指定した場合）。

metadataobject

請求書の作成時に渡したオブジェクト。変更されずにそのまま返されます。

coinobject | null

顧客が選んだコイン、または実際に支払われたコイン。id、symbol、networkを含みます。コインが選ばれるまではnullです。

requested_coinobject | null

通常はnullです。顧客が別のコインや別のネットワークで支払い、その決済が計上された場合、請求書で指定されたコインをcoinと同じフィールドで表します。誤ったコインまたは誤ったネットワークをご覧ください。

pay_addressstring | null

この請求書の入金アドレス。コインが選ばれるまではnullです。

pay_amountstring | null

選択したコインで送金する正確な金額。

network_fee_amountstring

pay_amountの一部：顧客が価格に加えて支払うガス手数料（コイン建て）。ない場合は0。

network_fee_usdstring

同じガス手数料（米ドル建て）。

rate_usdstring | null

選択したコイン1単位あたりの固定価格（米ドル建て）。

received_amountstring

これまでに着金した金額（選択したコイン建て）。

received_usdstring

着金した金額の米ドル換算額。

overpaid_amountstring

請求額を超えて支払われた金額（選択したコイン建て）。

refunded_amountstring

返金リンクでこの決済について返金した額（支払われたコイン建て）。返金がない場合は0です。

checkout_urlstring

請求書ページ。顧客をここに誘導して支払ってもらいます。

redirect_urlstring | null

支払い後に顧客が移動できる先。

expires_atISO 8601

決済が確認されない場合に請求書が期限切れになる日時。

paid_atISO 8601 | null

請求書が支払われた日時、またはnull。

created_atISO 8601

請求書が作成された日時。

{
  "id": "inv_…",
  "object": "invoice",
  "status": "open",
  "amount": "49.9",
  "currency": "USD",
  "amount_usd": "49.9",
  "description": "Annual plan",
  "order_id": "1042",
  "customer_email": "[email protected]",
  "metadata": { "plan": "annual" },
  "coin": null,
  "requested_coin": null,
  "pay_address": null,
  "pay_amount": null,
  "network_fee_amount": "0",
  "network_fee_usd": "0",
  "rate_usd": null,
  "received_amount": "0",
  "received_usd": "0",
  "overpaid_amount": "0",
  "refunded_amount": "0",
  "checkout_url": "https://cryptomerchant.online/pay/i/inv_…",
  "redirect_url": "https://yourstore.example/thanks",
  "expires_at": "2026-10-28T10:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-28T09:30:00.000Z"
}

請求書のステータス

open受付中

作成済み。顧客はまだコインを選んでいません。

awaiting_payment支払い待ち

コインが選ばれ、入金アドレスが割り当てられ、レートが固定されています。

confirming承認待ち

オンチェーンで決済が確認され、承認を待っています。

underpaid支払い不足

承認された決済の不足額が許容額を超えています。顧客は残りを支払うか、返金を求めることができます。

paid支払い済み

支払い済みで承認済み。手数料を差し引いた金額が残高に計上されています。一部返金してもこのステータスのままです。

expired期限切れ

決済が確認される前に時間切れになりました。

cancelledキャンセル済み

決済が確認される前に請求書がキャンセルされました。

refunded返金済み

支払い不足の請求書で顧客に送金分が返金されたか、支払い済みの請求書からあなたが受け取った額をすべて返金しました。

請求書を作成

POST/invoices

請求書を作成し、ステータス201で請求書オブジェクトを返します。顧客をそのcheckout_urlに誘導してください。

ボディパラメータ

amount必須number | string

価格。数値または10進数の文字列で指定します。0.50米ドル以上である必要があります。

currency任意string

価格の通貨。例：USD。デフォルトはUSDです。

description任意string

顧客が支払う対象の説明（最大300文字）。請求書ページに表示されます。

order_id任意string

請求書と注文を照合するための、自社の注文参照番号（最大120文字）。

customer_email任意string

顧客のメールアドレス。管理画面では決済が顧客ごとにまとめられます。

customer_name任意string

顧客の名前（最大120文字）。

redirect_url任意string

支払い後に顧客が移動できる完全なURL。

metadata任意object

最大4 KBの任意のJSONオブジェクト。請求書とWebhookで変更されずにそのまま返されます。

coin任意string

IDでコインを事前選択します。例：USDT.TRON。受け付けコインのいずれかである必要があります。

coinを事前選択すると、入金アドレスがすぐに割り当てられてレートが固定されるため、pay_addressとpay_amountが入力された状態になり、独自のインターフェースに支払い情報を表示できます。

curl https://cryptomerchant.online/api/v1/invoices \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "USD",
    "order_id": "1042",
    "description": "Annual plan",
    "customer_email": "[email protected]",
    "redirect_url": "https://yourstore.example/thanks",
    "metadata": { "plan": "annual" }
  }'

const res = await fetch("https://cryptomerchant.online/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.90",
    currency: "USD",
    order_id: "1042",
    description: "Annual plan",
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const invoice = await res.json();
// Send the customer to invoice.checkout_url

請求書の一覧を取得

GET/invoices

請求書を新しい順に、1ページずつ返します。

クエリパラメータ

status任意string

このステータスの請求書のみを返します。例：paid。上記のステータスのいずれかである必要があります。

limit任意number

返す請求書の数（1〜100）。デフォルトは20です。

starting_after任意string

請求書ID。次のページとして、その後に続く請求書を返します。

請求書はdataに含まれます。has_moreがtrueの場合は、starting_afterに最後に受け取った請求書のIDを設定して次のページをリクエストしてください。

curl "https://cryptomerchant.online/api/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "list",
  "data": [
    { "id": "inv_…", "object": "invoice", "status": "paid", … }
  ],
  "has_more": true
}

請求書を取得

GET/invoices/{id}

IDで指定した1件の請求書を返します。

curl https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $CM_SECRET_KEY"

請求書をキャンセル

POST/invoices/{id}/cancel

請求書をキャンセルします。請求書が未払いで、決済がまだ確認されていない場合にのみ有効です。

curl -X POST https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID/cancel \
  -H "Authorization: Bearer $CM_SECRET_KEY"

残高

GET/balances

ビジネスが保有する各コインの残高、米ドル建ての合計、およびガス残高を返します。

data[].coin

コインID。例：USDT.TRON。

data[].symbol

コインのシンボル。例：USDT。

data[].network

コインが存在するネットワーク。

data[].amount

保有しているコインの量（10進数の文字列）。

data[].usd

現在の価格での米ドル換算額。

total_usd

保有するすべてのコインの米ドル換算額の合計。

gas_balance_usd

ガス手数料の支払いに使われるガス残高（米ドル建て）。

curl https://cryptomerchant.online/api/v1/balances \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "balance",
  "data": [
    { "coin": "USDT.TRON", "symbol": "USDT", "network": "Tron", "amount": "…", "usd": "…" }
  ],
  "total_usd": "…",
  "gas_balance_usd": "…"
}

受け付けコイン

GET/coins

現在受け付けているコインを返します。各コインにはid、symbol、name、network、decimalsが含まれます。請求書を作成するときは、idをcoinとして使用します。例：

curl https://cryptomerchant.online/api/v1/coins \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "ETH.ETH",
      "symbol": "ETH",
      "name": "Ethereum",
      "network": "Ethereum",
      "decimals": 18
    },
    {
      "id": "USDT.ETH",
      "symbol": "USDT",
      "name": "Tether USD",
      "network": "Ethereum",
      "decimals": 6
    },
    {
      "id": "USDC.ETH",
      "symbol": "USDC",
      "name": "USD Coin",
      "network": "Ethereum",
      "decimals": 6
    }
  ]
}

決済リンクを作成

POST/payment-links

決済リンクを作成し、そのidと共有用のurlを含めて、ステータス201で返します。

ボディパラメータ

title必須string

顧客が支払う対象の名前（最大120文字）。

amount任意number | string

固定価格。省略すると、顧客が金額を入力できます。

currency任意string

価格の通貨。デフォルトはUSDです。

description任意string

顧客に表示される詳細な説明（最大300文字）。

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulting hour",
    "amount": "80",
    "currency": "USD"
  }'

{
  "id": "…",
  "object": "payment_link",
  "title": "Consulting hour",
  "description": null,
  "amount": "80",
  "currency": "USD",
  "active": true,
  "url": "https://cryptomerchant.online/pay/l/…",
  "created_at": "2026-10-28T09:30:00.000Z"
}

決済リンクの一覧を取得

GET/payment-links

最新の決済リンク100件を、新しい順にdataで返します。

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY"

出金オブジェクト

出金のWebhook（payout.sentとpayout.failed）は、dataにこのオブジェクトを含みます。収益分配によるパートナー分配分の出金も同じオブジェクトを使い、partner_shareがtrueになります。

idstring

出金ID。

objectstring

常にpayoutです。

coinstring

コインID。例：USDT.TRON。

amountstring

出金額（そのコイン建て）。

network_feestring

送金のガス手数料（そのコイン建て）。

to_addressstring

送金先のウォレットアドレス。

statusstring

queued、running、done、failedのいずれか。

tx_hashstring | null

送信後の、ブロックチェーン上のトランザクションID。

autoboolean

出金が人によるリクエストではなく自動で行われた場合はtrue。

partner_shareboolean

この出金が収益分配によるパートナー分配分で、パートナーのウォレットに送られた場合はtrue。

created_atISO 8601

出金が作成された日時。

{
  "id": "…",
  "object": "payout",
  "coin": "USDT.TRON",
  "amount": "120",
  "network_fee": "…",
  "to_address": "T…",
  "status": "done",
  "tx_hash": "…",
  "auto": true,
  "partner_share": true,
  "created_at": "2026-10-28T09:30:00.000Z"
}