V-REC API v1 / Online Learning & Token Pool / Merchant eKYC Preload / KYC R5.1 / Tenant Funding / Existing User Link / Crypto Wallet & Sales / Cards & Wallet Transactions v2.6.14

オンライン授業・Googleカレンダー・加盟店トークンプール

これは外部加盟店サーバー向けのAPIです。ブラウザにMerchant HMAC秘密鍵を置かず、利用者ログインを検証した自社バックエンドから呼び出してください。V-RECとSAKURAの双方で対象Merchantと会員所属を検証します。

本番前提条件: 専用の加盟店⇄SAKURA接続、権限の明示承認、SAKURA Connected Appsの再認可が必要です。共有接続で加盟店分離が保証できない場合は409で遮断されます。

全14エンドポイントのパス・パラメータ・エラーは下の「加盟店オンライン授業・カスタムトークン API」の折りたたみ詳細に掲載しています。 IN / OUT reference

無料講座の外部受講登録

POST /api/merchant/v1/learning/programs/331/enrollments
Content-Type: application/json
{"user_id":"usr_member_1234","learner_consent":true,"consent_reference":"consent-record-20261031-01"}

SAKURAとV-RECの双方で加盟店所属を確認。受講登録は明示権限が必要です。有料講座は422を返し、本人が会員用購入画面で申し込みます。

外部講義の受講完了通知

POST /api/merchant/v1/learning/sessions/371/complete
Content-Type: application/json
{"user_id":"usr_member_1234","idempotency_key":"course-371-user-1234","evidence_ref":"provider-attendance-371-1234","duration_seconds":3600}

授業の終了時刻を経過し、既存の出席・テスト・アンケート条件を満たした場合のみ完了になります。202は非同期・保留を含み、報酬やブロック確定を意味しません。報酬の任意金額指定はできません。

Googleカレンダー

GET progressのgoogle_calendar_add_urlは、会員がクリックして保存するGoogleカレンダー登録画面です。自動同期は会員が事前承認したGoogle OAuthでのみ行えます。未承認時は409、一部失敗は207を返します。

GET  /api/merchant/v1/learning/users/usr_member_1234/progress
POST /api/merchant/v1/learning/users/usr_member_1234/calendar-sync
{"program_id":331}

加盟店プールからのガスレス送金

POST /api/merchant/v1/token-pool/transfers
{"merchant_code":"mrc_your_merchant_code","user_id":"usr_member_1234","request_id":"merchant-token-20261031-00001","amount":"10.500000"}
GET /api/merchant/v1/token-pool/transfers/merchant-token-20261031-00001

送金実行にはACTIVE/FULL会員・Merchant紐付け・有効な受取ERCウォレット・別勘定のトークン原資・承認済みリレイヤーが必要です。USDT担保プールや授業報酬とは混同しません。submittedは送信受付でありconfirmedではありません。reconcile_requiredは手動照合の対象で自動再送しません。未検証のリレイヤー設定では送金機能は無効です。

外部サイト連携フロー · OpenAPI定義（YAML） · 加盟店履歴画面（ログイン後）

外部サイトから登録してeKYCリンクだけを本人へ送る

本フローにはCredentialへの明示権限 kyc.preload と kyc.link.issue が必要です。Merchant Portal → Merchant API で、同意取得の責任についての確認チェックを入れて加盟店自身が付与します（旧形式の全権限キーには含まれません）。通常のMerchant APIの users.write / kyc.read だけでは利用できません。本人が最終確認を完了しても、SAKURA/MatchMoveの審査結果がAPPROVEDになるまでは承認完了ではありません。

GET  /api/merchant/v1/profile-options
POST /api/merchant/v1/users             {"onboarding_mode":"ekyc_only", ...}
GET  /api/merchant/v1/users/{id}/kyc/schema
POST /api/merchant/v1/users/{id}/kyc/preload
     Idempotency-Key: unique-draft-request-id
     JSON: {"fields": {...}, "documents": {...}, "consent": {...}}
GET  /api/merchant/v1/users/{id}/kyc/preload-status
POST /api/merchant/v1/users/{id}/kyc/preload-reconcile  # only authorized correction
POST /api/merchant/v1/users/{id}/kyc/onboarding-link
     → ekyc_url (secure delivery by merchant to verified user)
GET  /api/merchant/v1/users/{id}/kyc  → APPROVED / REVIEW / PENDING / ...
Webhook: user.kyc.updated (optional)

2026-10-27：preloadではbirthday/title/gender/nationalityを毎回明示し、18歳未満は422です。emailまたはphoneの重複は409です。外部eKYC完了だけではAPPROVEDにならず、SAKURAが未承認ならfinal_reviewです。リンク発行後は本人情報を変更できません。

全てのリクエストに既存のHMACヘッダーが必要です。画像はJSON内Base64として署名し、SAKURAへmultipart転送します。eKYCリンクを加盟店サーバーのログや第三者分析へ保存しないでください。

Flow guide · OpenAPI定義（YAML）

カード種別の一覧を取得する（15分キャッシュ）

これは発行済みカード一覧ではありません。SAKURAに登録されたMatchMoveカード種別（物理・バーチャル）の商品コード、画像、通貨、CVVメタ情報、発行上限設定等を参照します。加盟店HMACで署名し、cards.read権限とSAKURA Connected Appsのcards権限が必要です。

GET /api/merchant/v1/card-types
GET /api/merchant/v1/card-types?form_factor=physical
GET /api/merchant/v1/card-types?form_factor=virtual&code=seguammccard

成功時はdata[]（id、code、name、description、form_factor、personalised_order、token、currency、image、details、created_at、updated_at）、total、filters、metaを返します。detailsは発行元の値によってobjectまたは空配列[]です。

{"data":[{"id":1,"code":"seguammcpcard","name":"Sakura Exchange, Guam Inc. Physical Card","description":"Sakura Exchange, Guam Inc. Physical Card","form_factor":"physical","personalised_order":false,"token":{"type":"CVV","generation":"static"},"currency":["USD"],"image":{"large":"https://assets.mmvpay.com/global/products/seguammcpcard/card-large.png"},"details":{},"created_at":"2025-04-27 03:45:57","updated_at":"2026-10-29 02:30:15"}],"total":1,"filters":{"form_factor":"physical","code":null},"meta":{"source":"vrec_cache","stale":false,"refreshed_at":"2026-11-05T04:00:00+00:00","next_refresh_at":"2026-11-05T04:15:00+00:00","cache_ttl_seconds":900}}

JSONは説明用サンプルです。SAKURAはMatchMove GET /users/wallets/cards/typesを900秒単位で同期し、mm_card_typesを更新します。V-RECはSAKURAの次回更新期限に合わせてローカルファイルキャッシュを更新するため、15分＋15分にはなりません。通信失敗時はmeta.stale=trueで最終データを返し、保持データもなければ503です。最新データでも発行許可を保証しません。

HTTP: 200, 401, 403, 422, 429, 503. Cache-Control: private, no-store.

下の詳細IN/OUT仕様へ · OpenAPI定義（YAML）

アタッチ済みユーザーの既存SAKURAカードを取得

既定でV-RECに登録済みのカードだけでなく、本人のSAKURAに以前から存在する個人名義のMastercardも返します。SAKURA Connected Appsのcards権限、cards.read、ACTIVE/FULL所属およびcan_view_balance=1が必要です。別V-RECプログラム発行カードと法人加盟店カードは除外します。

GET /api/merchant/v1/users/usr_example/cards
GET /api/merchant/v1/users/usr_example/cards?include_existing=false
GET /api/merchant/v1/users/usr_example/cards/skc_0123456789abcdef0123456789abcdef/transactions?from=2026-10-10&to=2026-11-09

レスポンスdata[]のsourceはVREC_LOCAL / VREC_AND_SAKURA / SAKURA_ONLY、originはVREC_LOCAL / VREC_ISSUED / SAKURA_EXISTINGです。SAKURA_ONLYカードのidは閲覧用 skc_... であり、カード停止・PIN・機密カード表示・発行会社ステータスのAPIには使用できません。card_...は従来のV-REC公開IDです。

残高は返しません。状態はSAKURA保存記録でありMatchMoveリアルタイム照会ではありません。SAKURA側の最大100件取得で切り詰められた場合はmeta.sakura_truncated=trueです。SAKURA障害時は503を返し、空配列に置き換えません。include_existing=falseを付けると旧V-RECローカル一覧のみを返します。

個人の保有カード情報を加盟店へ開示するため、契約・個人情報の利用目的・閲覧権限が適切であることを確認してください。アタッチ操作だけで別サービスの金融情報閲覧への法的同意が当然に得られるわけではありません。

OpenAPI定義（YAML） · 下の詳細IN/OUT仕様

アタッチ済みユーザーの既存SAKURAカードを取得

既定でV-RECに登録済みのカードだけでなく、本人のSAKURAに以前から存在する個人名義のMastercardも返します。SAKURA Connected Appsのcards権限、cards.read、ACTIVE/FULL所属およびcan_view_balance=1が必要です。別V-RECプログラム発行カードと法人加盟店カードは除外します。

GET /api/merchant/v1/users/usr_example/cards
GET /api/merchant/v1/users/usr_example/cards?include_existing=false
GET /api/merchant/v1/users/usr_example/cards/skc_0123456789abcdef0123456789abcdef/transactions?from=2026-10-10&to=2026-11-09

レスポンスdata[]のsourceはVREC_LOCAL / VREC_AND_SAKURA / SAKURA_ONLY、originはVREC_LOCAL / VREC_ISSUED / SAKURA_EXISTINGです。SAKURA_ONLYカードのidは閲覧用 skc_... であり、カード停止・PIN・機密カード表示・発行会社ステータスのAPIには使用できません。card_...は従来のV-REC公開IDです。

残高は返しません。状態はSAKURA保存記録でありMatchMoveリアルタイム照会ではありません。SAKURA側の最大100件取得で切り詰められた場合はmeta.sakura_truncated=trueです。SAKURA障害時は503を返し、空配列に置き換えません。include_existing=falseを付けると旧V-RECローカル一覧のみを返します。

個人の保有カード情報を加盟店へ開示するため、契約・個人情報の利用目的・閲覧権限が適切であることを確認してください。アタッチ操作だけで別サービスの金融情報閲覧への法的同意が当然に得られるわけではありません。

OpenAPI定義（YAML） · 下の詳細IN/OUT仕様

アタッチ済みユーザーの既存SAKURAカードを取得

既定でV-RECに登録済みのカードだけでなく、本人のSAKURAに以前から存在する個人名義のMastercardも返します。SAKURA Connected Appsのcards権限、cards.read、ACTIVE/FULL所属およびcan_view_balance=1が必要です。別V-RECプログラム発行カードと法人加盟店カードは除外します。

GET /api/merchant/v1/users/usr_example/cards
GET /api/merchant/v1/users/usr_example/cards?include_existing=false
GET /api/merchant/v1/users/usr_example/cards/skc_0123456789abcdef0123456789abcdef/transactions?from=2026-10-10&to=2026-11-09

レスポンスdata[]のsourceはVREC_LOCAL / VREC_AND_SAKURA / SAKURA_ONLY、originはVREC_LOCAL / VREC_ISSUED / SAKURA_EXISTINGです。SAKURA_ONLYカードのidは閲覧用 skc_... であり、カード停止・PIN・機密カード表示・発行会社ステータスのAPIには使用できません。card_...は従来のV-REC公開IDです。

残高は返しません。状態はSAKURA保存記録でありMatchMoveリアルタイム照会ではありません。SAKURA側の最大100件取得で切り詰められた場合はmeta.sakura_truncated=trueです。SAKURA障害時は503を返し、空配列に置き換えません。include_existing=falseを付けると旧V-RECローカル一覧のみを返します。

個人の保有カード情報を加盟店へ開示するため、契約・個人情報の利用目的・閲覧権限が適切であることを確認してください。アタッチ操作だけで別サービスの金融情報閲覧への法的同意が当然に得られるわけではありません。

OpenAPI定義（YAML） · 下の詳細IN/OUT仕様

ウォレット履歴・カード別履歴・加盟店台帳の使い分け

3つの取引履歴はデータ元も対象範囲も違います。カード発行が成功していても、カード決済がなければカード別履歴は空になる場合があります。ウォレット取引をカード別履歴に合算したり、加盟店残高台帳として扱わないでください。

認証と権限： すべてMerchant HMAC署名＋transactions.readが必要です。MatchMoveのライブ照会はACTIVE/FULLの加盟店所属かつcan_view_balance=1が必要です。さらにウォレット履歴はSAKURA Connected Appsのbalances、カード別履歴はcards権限が必要です。

GET /api/merchant/v1/users/usr_example/matchmove-wallet-transactions?page=1&limit=20
GET /api/merchant/v1/users/usr_example/cards/card_example/transactions?from=2026-10-05&to=2026-11-04&page=1&limit=20

ウォレット取引の絞り込み検索

検索条件を指定するとカーソル方式へ切り替わります。pageを増やすのではなく、next_cursorを次回のcursorとして渡し、全ての検索条件とlimitを同じまま送信します。検索条件なしは従来のpage/limitのままです。

GET /api/merchant/v1/users/usr_example/matchmove-wallet-transactions?category=purchase&indicator=debit&from=2026-11-01&to=2026-11-04&limit=20

// next_cursorが返った場合（同じフィルターを繰り返す）
GET /api/merchant/v1/users/usr_example/matchmove-wallet-transactions?category=purchase&indicator=debit&from=2026-11-01&to=2026-11-04&limit=20&cursor=NEXT_CURSOR

OpenAPI定義（YAML） · 以下の加盟店API仕様で詳細を見る

Payout・Tenant Funding・Transactionsを正しく区別する

V-RECは1つの財布ではありません。資金の出所ごとに正本とイベントが違うため、一覧やAPIの結果は合算せず、参照IDで突き合わせます。

通貨とトークンの表示例

連携例：直接資金割当を帳票に表示する

Merchant HMAC: POST /api/merchant/v1/tenant-funding/allocations
  → status = COMPLETED, allocation.public_id = vta_...
Authenticated V-REC user: GET /api/v1/me/tenant-allocations
  → data[...].public_id = vta_..., amount = "10.00000000", currency = "USD"
Authenticated V-REC user: GET /api/v1/me/ledger-entries
  → entry_type = CREDIT, reference_type = SAKURA_TENANT_ALLOCATION
User payouts API: GET /api/v1/me/payouts
  → { "data": [] } (VALID: no corporate payout took place)

読み方

下のAPI行をタップすると、そのAPIだけの入力仕様・出力仕様・期待レスポンス・エラー一覧が展開されます。Required欄の conditional / dynamic は、前段APIの状態やSAKURA KYCFORMの定義によって必須性が変わる項目です。

X-VREC-Merchant-Key: <value>
X-VREC-Timestamp: <value>
X-VREC-Nonce: <value>
X-VREC-Signature: <value>

METHOD + "\n" + PATH + "\n" + CANONICAL_QUERY + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + SHA256(raw_body)

既存SAKURAユーザーをV-RECへ接続する

既存SAKURA identityはPOST /api/merchant/v1/usersで再作成しません。MerchantはUserのemailやSAKURA User IDを指定せず、本人同意用Link Requestを作成し、返されたauthorization_urlを本人へ渡します。本人がSAKURAへログインして承認したidentityだけがV-RECへ接続されます。

Merchant backend
  POST /api/merchant/v1/user-links + Idempotency-Key
        ↓ authorization_url
User opens SAKURA consent page
        ↓ sign in + approve
SAKURA → V-REC callback (one-time code + state)
        ↓ code exchange / stable SAKURA user UUID
V-REC creates or reuses Global User + Tenant membership
        ↓
Merchant polls GET /api/merchant/v1/user-links/{id}
        ↓
COMPLETED + linked_user_id + membership(FULL or READONLY)

アンホステッドウォレット・ローテーション・ガスレス送金

ウォレットはSAKURAのアンホステッドERCウォレットです。BIP-39シードフレーズ（12語）は作成/入れ替え直後に1回だけ返され、秘密鍵は本人のウォレットパスワードで暗号化されます。V-RECはシードフレーズ・秘密鍵・ウォレットパスワードを保存しません。ガスレス送金ではSAKURAのリレイヤーがガス代（ETH）を負担します。

V-REC user (session)
  POST /api/v1/me/wallet            current_password step-up + wallet_password
        ↓ 201 + mnemonic (once)  → write down 12 words
  GET  /api/v1/me/wallet            address + USDT/ETH balances + gasless eligibility
  POST /api/v1/me/wallet/address-check   (address poisoning check)
  POST /api/v1/me/wallet/gasless-transfer  Idempotency-Key + wallet_password
        ↓ 201 SUBMITTED + tx_hash   |  202 transfer_status_unknown → GET /api/v1/me/wallet/requests/{key}
  POST /api/v1/me/wallet/rotate     step-up + new_wallet_password + reason → new mnemonic (once)

V-REC server → SAKURA Connected Apps (scopes crypto_wallet / crypto_wallet_manage)
  /api/integrations/vrec/users/{ref}/wallet*   Bearer + X-VRec-Proof, idempotency_key per write

加盟店経由の暗号資産による購入

利用者はUSDTまたは加盟店の独自トークンを代金として、SGP-USDまたは加盟店が定めたポイントを購入します。SAKURA EXCHANGEのライセンスに基づく販売で、両替ではありません。1件ごとに契約番号・売主・価格・手数料を確定し、本人の同意とウォレットパスワードで代金を支払います。

GET  /api/v1/me/wallet/purchase-catalog
POST /api/v1/me/wallet/purchase-quotes          Idempotency-Key  → contract_no (QUOTED, 10 min)
POST /api/v1/me/wallet/purchases/{contract}/confirm  accept_terms + wallet_password → PAYMENT_SUBMITTED
     … 12 confirmations → COMPLETED (SGP-USD as merchant-route lot / points)
GET  /api/merchant/v1/crypto-sales               (Merchant HMAC, crypto_sales.read)