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

Online learning, Google Calendar & merchant token pool

These are merchant backend APIs, never browser-side secret-bearing APIs. Verify the logged-in learner on your backend; V-REC and SAKURA both enforce membership and merchant binding.

Production prerequisites: Requires an isolated merchant-to-SAKURA connection, operator-granted credential scopes and explicit Connected Apps reauthorization. Unisolated shared connections fail closed with 409.

See the expandable “Merchant Learning & Custom Token Pool API” cards below for all 14 endpoint inputs, outputs and errors. IN / OUT reference

Consent-based free course enrollment

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"}

Both systems validate merchant membership. Explicit permission is required. Paid courses return 422 and must be purchased by the member.

External lesson completion evidence

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}

The lesson must have ended. SAKURA evaluates attendance, quiz and survey rules. HTTP 202 can mean pending; it is not token or blockchain confirmation. Reward amount is fixed by the configured lesson.

Google Calendar

GET progress supplies google_calendar_add_url for a user-clicked Google save screen. Automatic sync requires the user’s prior Google OAuth approval; missing authorization returns 409, partial failure may return 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}

Gasless transfer from a merchant pool

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

Requires ACTIVE/FULL membership, matching merchant, active ERC recipient wallet, dedicated custom-token backing and approved relayer. This is neither the USDT collateral pool nor a lesson reward. submitted is not confirmed; reconcile_required must not be automatically rebroadcast. Payout stays disabled until the relayer is verified.

External integration workflow · OpenAPI YAML · Merchant dashboard (login required)

Merchant-driven onboarding: deliver only the eKYC link

Requires the explicit credential scopes kyc.preload and kyc.link.issue, which the Merchant grants in Merchant Portal → Merchant API after acknowledging its consent obligations (never included in a legacy "All" key). Standard users.write / kyc.read do not enable this flow. Completing the browser flow is not provider approval: wait until SAKURA/MatchMove reports 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: Explicit birthday/title/gender/nationality on every preload, applicants must be at least 18. Duplicate email/phone gives 409. Provider completion alone is not approval: final_review remains pending until SAKURA approval. Identity is locked after link issuance.

Every request uses existing Merchant HMAC headers. Base64 evidence is signed in JSON and forwarded to SAKURA as multipart. Never log or share eKYC bearer links with analytics services.

Flow guide · OpenAPI YAML

List available card product types (15-minute cache)

This is NOT an issued-cards endpoint. It returns MatchMove product codes, physical/virtual types, artwork, currencies, CVV metadata and issuer limits. Requires signed Merchant HMAC with cards.read and a connected SAKURA cards grant.

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

Response: data[] (id, code, name, description, form_factor, personalised_order, token, currency, image, details, created_at, updated_at), total, filters, meta. details may be an object or [] depending on provider data.

{"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}}

Example JSON is illustrative. SAKURA refreshes the MatchMove catalog on a 900-second cycle and upserts mm_card_types; V-REC aligns its file-cache expiry to the SAKURA refresh deadline, so the delay does not accumulate. On provider failure, meta.stale=true indicates last-known data; 503 means no usable data. Catalog entries do not authorize card issuance.

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

See full request/response contract below · OpenAPI YAML

Read pre-existing SAKURA cards of an attached V-REC user

The default card list combines V-REC local cards with the attached identity’s existing personal Mastercard records in SAKURA. Requires cards.read, SAKURA cards grant, ACTIVE/FULL membership and can_view_balance=1. Cards issued to other V-REC programs and corporate Merchant-owned cards are excluded.

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 indicates VREC_LOCAL / VREC_AND_SAKURA / SAKURA_ONLY; origin indicates VREC_LOCAL / VREC_ISSUED / SAKURA_EXISTING. SAKURA_ONLY cards have read-only skc_... IDs, which cannot be used for freeze, PIN, sensitive-card, or issuer-status APIs. Local card_... IDs are unchanged.

The card list does not include balances and is not a live issuer-status check. SAKURA may cap its inventory at 100 items (meta.sakura_truncated=true). SAKURA outages return 503, not a fabricated empty list. Use include_existing=false for the old V-REC-local-only response.

Card disclosure to a Merchant must have an appropriate legal basis and documented data-use purpose. Linking an identity does not automatically grant legal permission to disclose all separate financial activity.

OpenAPI YAML · Detailed API contract below

Read pre-existing SAKURA cards of an attached V-REC user

The default card list combines V-REC local cards with the attached identity’s existing personal Mastercard records in SAKURA. Requires cards.read, SAKURA cards grant, ACTIVE/FULL membership and can_view_balance=1. Cards issued to other V-REC programs and corporate Merchant-owned cards are excluded.

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 indicates VREC_LOCAL / VREC_AND_SAKURA / SAKURA_ONLY; origin indicates VREC_LOCAL / VREC_ISSUED / SAKURA_EXISTING. SAKURA_ONLY cards have read-only skc_... IDs, which cannot be used for freeze, PIN, sensitive-card, or issuer-status APIs. Local card_... IDs are unchanged.

The card list does not include balances and is not a live issuer-status check. SAKURA may cap its inventory at 100 items (meta.sakura_truncated=true). SAKURA outages return 503, not a fabricated empty list. Use include_existing=false for the old V-REC-local-only response.

Card disclosure to a Merchant must have an appropriate legal basis and documented data-use purpose. Linking an identity does not automatically grant legal permission to disclose all separate financial activity.

OpenAPI YAML · Detailed API contract below

Read pre-existing SAKURA cards of an attached V-REC user

The default card list combines V-REC local cards with the attached identity’s existing personal Mastercard records in SAKURA. Requires cards.read, SAKURA cards grant, ACTIVE/FULL membership and can_view_balance=1. Cards issued to other V-REC programs and corporate Merchant-owned cards are excluded.

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 indicates VREC_LOCAL / VREC_AND_SAKURA / SAKURA_ONLY; origin indicates VREC_LOCAL / VREC_ISSUED / SAKURA_EXISTING. SAKURA_ONLY cards have read-only skc_... IDs, which cannot be used for freeze, PIN, sensitive-card, or issuer-status APIs. Local card_... IDs are unchanged.

The card list does not include balances and is not a live issuer-status check. SAKURA may cap its inventory at 100 items (meta.sakura_truncated=true). SAKURA outages return 503, not a fabricated empty list. Use include_existing=false for the old V-REC-local-only response.

Card disclosure to a Merchant must have an appropriate legal basis and documented data-use purpose. Linking an identity does not automatically grant legal permission to disclose all separate financial activity.

OpenAPI YAML · Detailed API contract below

Which transaction feed should you use?

These three feeds have different data sources and scopes. Successful card issuance does not guarantee a card purchase. Never merge wallet events into card statements or represent issuer activity as Merchant ledger entries.

Authentication and access: All three use signed Merchant HMAC with transactions.read. Live MatchMove feeds require ACTIVE/FULL membership and can_view_balance=1; the wallet endpoint additionally requires SAKURA Connected Apps balances while the card endpoint requires 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

Filtering live wallet history

Any filter activates cursor pagination: pass next_cursor as the next cursor with exactly the same filters and limit. Do not increment page. Without filters, page/limit behavior is unchanged.

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 · View full endpoint contracts below

How Payout, Tenant Funding and Transactions differ

V-REC does not expose one fungible wallet. Every source has its own system of record. Keep transaction IDs and reconcile related events; never blindly sum different ledgers.

How currencies and tokens are displayed

Example: reconcile one direct allocation

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)

How to read this reference

Tap an API row to expand the complete contract for that endpoint. Required values marked conditional or dynamic depend on prior state or the current SAKURA KYCFORM definition.

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)

Attach an existing SAKURA user to V-REC

Do not recreate an existing SAKURA identity through POST /api/merchant/v1/users. The Merchant must not select an identity by email or SAKURA user id. Create a consent Link Request, give its authorization_url to the user, and only the SAKURA identity authenticated and approved by that user is attached to 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)

Unhosted wallet, rotation and gasless transfer

The wallet is SAKURA's unhosted ERC wallet. The 12-word BIP-39 seed phrase is returned exactly once after create/rotate, and the private key is encrypted with the user's wallet password. V-REC never stores the seed phrase, key or wallet password. For gasless transfers SAKURA's relayer pays the gas (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

Merchant-route purchases paid in crypto

Users purchase SGP-USD or merchant-defined points, paying with USDT or the merchant token. Sold under the SAKURA EXCHANGE licence; not a currency exchange. Each purchase fixes a contract number, seller, price and fees, then the user accepts and pays with the wallet password.

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)