Sign in
決済と出金/Payout API

Payout API

マーチャント残高から任意のブロックチェーンアドレスへ出金します。

Payout API を使用すると、マーチャント残高から任意のブロックチェーンアドレスへプログラム的に資金を出金できます。

すべての Payout エンドポイントでは、sign 署名の生成に専用の Payout API key を使用する必要があります。このキーは通常の API キーとは異なり、プロジェクト設定で生成する必要があります。

出金を作成する

マーチャント残高からの出金リクエストを作成します。

POST/v1/payout

リクエストパラメータ

FieldTypeRequiredDescription
currencystringyes出金通貨(References を参照)
networkstringyesネットワークコード(References を参照)
amountstringyes出金額
to_addressstringyes受取人のブロックチェーンアドレス
order_idstringno冪等性キー — プロジェクト内で一意。同じ order_idPOST を再送信しても新しい出金は作成されず、既存のものが返されます
url_callbackstringno出金 Webhook の URL。この出金で Webhook を無効にする場合は省略します
memostring | nullno宛先タグ/メモ。現在は TON および SOL ネットワークでのみ使用、最大 255 文字
from_currencystringno出金時に引き落とし、currency へ自動換算するソース残高。残高を USDT のような安定コインで保持したまま、ボラタイルな資産(BTCETH、…)で出金できます — ボラタイルな暗号資産を自分で保有する必要はありません。"USDT" を指定すると USDT 残高から引き落とします
fee_optionstringno手数料の課金方法。deduct(デフォルト) — ネットワーク手数料 + プラットフォーム手数料が amount から差し引かれ、受取人は amount - fees を受け取ります。add — 手数料が上乗せされ、マーチャントから amount + fees が引き落とされ、受取人は正確に amount を受け取ります

冪等性。 プロジェクト内で出金は order_id によって一意になります。同じ order_id で同じ POST を再送信しても 安全です — API は新しい出金を作成する代わりに既存の出金を返します。本番の出金では常に order_id を渡してください。

リクエスト例

Shell
curl -X POST https://api.2328.io/api/v1/payout \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"TRX","network":"TRX-TRC20","amount":"1.00","to_address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","order_id":"9ed25264-8be4-439f-acf5-2a8732538d27","url_callback":"https://your-site.com/webhook/payout","memo":null,"fee_option":"deduct"}'

レスポンス例

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dea62-1727-72aa-ac2c-eaf2ade193ef",
    "order_id": "9ed25264-8be4-439f-acf5-2a8732538d27",
    "status": "pending",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "1.00",
    "merchant_amount": "1",
    "network_amount": "0.89",
    "amount_usd": "0.33",
    "to_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "memo": null,
    "txid": null,
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-02T23:29:50+03:00",
    "updated_at": "2026-05-02T23:29:50+03:00"
  }
}

手数料。 デフォルトは fee_option: deduct — ネットワーク手数料 + プラットフォーム手数料が amount から差し引かれます(受取人は amount - fees を受け取る)。fee_option: add を渡すと手数料が上乗せされます — 受取人は正確に amount を受け取り、マーチャントから amount + fees が引き落とされます。

出金を試算する

出金額と手数料を 出金を作成せず、残高を引き落とすこともなく見積もります。確認前にユーザーが実際に受け取る(または支払う)正確な金額を表示するのに使います。

POST/v1/payout/calc

リクエストパラメータ

出金を作成する と同一です — フィールドも署名も同じ。order_idurl_callbackto_addressmemo も受け付けますが無視されます: 出金は永続化されず、callback も送信されません。

リクエスト例

Shell
curl -X POST https://api.2328.io/api/v1/payout/calc \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"USDT","network":"TRX-TRC20","amount":"100","fee_option":"add"}'

レスポンス例

JSON
{
  "state": 0,
  "result": {
    "currency": "USDT",
    "network": "TRX-TRC20",
    "amount": "100",
    "fee_option": "add",
    "merchant_amount": "103.00000000",
    "network_amount": "100",
    "total_fee": "3.00000000",
    "total_fee_usd": "3.00000000"
  }
}

プレビュー専用。 このエンドポイントは読み取り専用です — 残高は引き落とされず、出金レコードも作成されません。UI に手数料の内訳を表示するために、必要なだけ呼び出して構いません。

出金ステータス

出金リクエストのステータスを取得します。

GET/v1/payout/status/{uuid}

パスパラメータ

FieldTypeRequiredDescription
uuidstringyes出金 UUID(作成時の result.uuid

レスポンス例

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
    "order_id": "4dfdcc84402b1185b71cbe399321533e",
    "status": "completed",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "3.00",
    "merchant_amount": "3.00",
    "network_amount": "3.00",
    "amount_usd": "1.04",
    "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
    "memo": null,
    "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-07T00:08:38+03:00",
    "updated_at": "2026-05-07T00:08:54+03:00",
    "from_currency": "USDT",
    "debited_amount": "1.050735",
    "debited_currency": "USDT"
  }
}

この GET リクエストでは、署名は空のボディから計算します: hash_hmac('sha256', base64_encode(''), $apiKey)

レスポンスフィールド

POST /v1/payout および GET /v1/payout/status/{uuid}result で返されるフィールド:

FieldTypeDescription
uuidstringシステムにより割り当てられた出金 UUID
order_idstring内部の出金識別子(プロジェクト内で一意)
statusstring現在の出金ステータス(下記参照)
currencystring出金通貨
networkstringネットワークコード
amountstringリクエストされた出金額
merchant_amountstringマーチャント残高から引き落とされた金額
network_amountstring実際にオンチェーンで送信された金額(ネットワーク手数料 + プラットフォーム手数料控除後)
amount_usdstring出金額の USD 換算
to_addressstring受取人のブロックチェーンアドレス
memostring | null宛先タグ/メモ(TON、SOL)。それ以外は null
txidstring | nullブロックチェーントランザクションハッシュ。トランザクションが送信されるまでは null
block_numberint | nullトランザクションが含まれたブロック番号。含まれるまでは null
error_typestring | nullstatus = failed のときの失敗理由(下記の Error types を参照)。それ以外は null
created_atstring (ISO 8601)出金作成日時
updated_atstring (ISO 8601)最終ステータス変更日時
from_currencystring | null自動換算が使われた場合に出金が引き落とされたソース残高(例:BTC 出金に対する USDT)。換算が行われなかった場合は null
debited_amountstring | null換算後にソース残高から実際に引き落とされた金額。自動換算が使われる場合のみ存在
debited_currencystring | nulldebited_amount の通貨 — 資金が引き落とされた残高

出金ステータス

status フィールドは以下の値を取り得ます:

StatusDescription
pending作成済み、処理待ち
completed正常に完了 — txid が設定される
failed送信エラー — error_type を参照
cancelledキャンセル済み

エラータイプ

status = failed の場合、error_type フィールドが理由を示します:

CodeDescription
aml_riskAML リスクチェックにより出金がブロックされました(受取アドレスが高リスクとしてフラグ付け)

Webhook 通知

出金のステータスが変化すると、システムは出金作成時に渡された url_callback URL に POST Webhook を送信します。url_callback が指定されていない場合、その出金には Webhook は送信されません。

  • Method: POST
  • Content-Type: application/json
  • Signature: リクエストボディの sign フィールド。Payout API key(出金リクエストの署名と同じキー)で計算されます。

ペイロードは GET /v1/payout/status/{uuid}result オブジェクトに、検証用の sign フィールドを追加したものです。

ペイロード

JSON
{
  "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
  "order_id": "4dfdcc84402b1185b71cbe399321533e",
  "status": "completed",
  "currency": "TRX",
  "network": "TRX-TRC20",
  "amount": "3.00",
  "merchant_amount": "3.00",
  "network_amount": "3.00",
  "amount_usd": "1.04",
  "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
  "memo": null,
  "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
  "block_number": null,
  "error_type": null,
  "created_at": "2026-05-07T00:08:38+03:00",
  "updated_at": "2026-05-07T00:08:54+03:00",
  "from_currency": "USDT",
  "debited_amount": "1.050735",
  "debited_currency": "USDT",
  "sign": "925ad7bf3d6841864101f7cc2c7e30652e70a06cdb04dbe07a0129480000ce4a"
}

署名の検証。 支払い Webhook と同じアルゴリズムを使用しますが、通常の API キーではなく Payout API key で署名します。sign フィールドを取り除き、残りのペイロードを JSON エンコードし、Base64 エンコードしてから hash_hmac('sha256', $base64, $payoutApiKey) を計算し、受信した sign と比較してください。