V-REC API / 現行実装

Partner APIの署名方式

Partner APIの署名文字列はMerchant APIと異なります（並び順が違い、クエリは含めません）。Merchant API用の実装を流用しないでください。

X-VREC-Key: vrec_...            # Partner key ID
X-VREC-Timestamp: 1792540800    # Unix seconds, within ±300 s
X-VREC-Nonce: 7d1c...           # unique, 1-128 chars, never reused
X-VREC-Signature: hex HMAC-SHA256

body_hash = hex(SHA256(raw_body))          # GET: SHA256("") = e3b0c442...b855
message   = TIMESTAMP + "\n" + NONCE + "\n" + METHOD + "\n" + PATH + "\n" + body_hash
signature = hex(HMAC-SHA256(message, partner_secret))
# PATH = URL path only, e.g. /api/v1/payouts/po_abc/fund

POSTはすべてJSONオブジェクトのボディが必須です。項目がない場合は {} を送信してください（空ボディは400 invalid_json）。認証エラーは401（partner_not_authorized / stale_timestamp / invalid_nonce / invalid_signature）、nonce再利用は409 replayed_nonce、許可IP外は403 ip_not_allowed です。

作成から入金までの手順

金額の表示通貨はUSDです。source_assetとdestination_assetの両方を指定し、同じ資産種別の場合に限り受付します。実送金できるのはMATCHMOVEUSD同士だけで、USD→USD、SGP-USD→SGP-USDは作成できても /fund で拒否されます。異種資産間・自動交換は禁止です。

POST /api/v1/payouts
Idempotency-Key: corp-20261021-0001
{
  "beneficiary_id": "VREC-...",
  "merchant_id": "mrc_...",            // optional, see OpenAPI
  "amount": "100.00",                  // string, max 2 decimals
  "currency": "USD",
  "funding_mode": "MERCHANT_BALANCE",
  "source_asset": "MATCHMOVEUSD",
  "destination_asset": "MATCHMOVEUSD",
  "external_reference": "INVOICE-2026-10-001",   // required, unique per Partner
  "purpose": "corporate_payout"                  // optional, max 80 chars
}
→ 201 {"id":"po_...","status":"PENDING_FUNDS","merchant_transfer_status":null, ...}

POST /api/v1/payouts/po_.../fund        body: {}
→ 200 {"status":"CREDITED","merchant_transfer_status":"COMPLETED","provider_tx_id":"...", ...}

事前条件：承認済みPartnerとMerchantの紐付け、受取人のKYC承認とACTIVE/FULLの所属、SAKURA Connected Appのcorporate_payout権限、そしてSAKURAの加盟店管理画面「V-REC Corporate Payout」で加盟店が送金上限（1件・日次、UTC日付）を有効化していること。未設定の場合 /fund は RETRYABLE（corporate_payout_policy_not_enabled）になります。

上限超過時：/fund が RETRYABLE（corporate_payout_merchant_approval_required）を返し、SAKURAに承認申請が作られます。加盟店がSAKURAで個別承認（24時間有効）した後、GET /approval-status で fund_retry_permitted=true を確認してから、同じPayoutで /fund を再実行してください。承認されない場合は /cancel できます。

全パラメータ・応答・エラーコードはPayout OpenAPIを参照 →

SAKURAを資金状態の正本として扱い、V-REC Merchant APIから安全に操作

Tenant FundingではV-RECがテナント利用可能額を独自正本として持ちません。GET balance / capacityでSAKURA正本を確認し、直接AllocationまたはPayout経由Fundingを実行します。新規資金移転はACTIVE/FULLかつSource Merchant=Tenant MerchantのMembershipだけが対象です。READONLYはmask済みカード参照を維持できますが、Tenant資金の新規割当には使えません。

現在の資金操作はMerchant APIのtenant_funding.read/writeだけでは承認されません。既存SAKURA Connected Appは明示的にtenant_fundingへ再認可し、接続Merchant・origin・program、Tenant binding、ENFORCED、api_execute_enabledおよび照合状態を確認してください。権限不足やREADONLYは資金割当を拒否します。

Direct allocation
GET  /tenant-funding/balance
GET  /tenant-funding/users/{id}/capacity
        ↓ eligible / available
POST /tenant-funding/allocations + Idempotency-Key
        ↓
V-REC re-checks Membership + SAKURA status
        ↓
SAKURA /api/integrations/vrec/tenant-funding/fund
        ↓ 201 COMPLETED / 409 REJECTED (not executed) / 202 UNKNOWN (retry same key)
GET  /tenant-funding/allocations?updated_since=…  (cron result collection)
V-REC creates provenance lot with expiry snapshot

Payout-based funding (historical LEGACY_REFERENCE payouts only)
existing LEGACY_REFERENCE payout, KYC APPROVED
        ↓ tenant-funding cron, same SAKURA fund guard
        ↓ COMPLETED
Payout = CREDITED
# New payouts (MERCHANT_BALANCE) are never funded by Tenant Funding.

180日制限等のexpiryはSAKURAがAllocation実行時に返すeffective snapshotをV-REC lotへ保存します。V-REC側の表示・利用・returnで期限を再起算しません。

SAKURAの /api/integrations/vrec/tenant-funding/* は引き続きConnected App間の内部APIです。外部Merchantはそれを直接呼ばず、上記 /api/merchant/v1/tenant-funding/* を使用します。

現時点での公開API境界

Merchant APIには直接fund endpointはありません。 ユーザーへの受領指示はPartner Payout APIで作成します。Merchantでバーチャルカード発行が可能ですが運営者のcards.issue権限が必要です。PAN/CVVはMerchantサーバーに返しません。本人がV-REC画面でパスワードを入力し、5分間有効の一度限りのリンクから参照できます。Merchantはcards.manageの明示許可でフリーズ/解除が可能ですが、PINやPAN/CVVは取得できません。