V-REC API / Current implementation

Partner API request signing

The Partner API canonical string differs from the Merchant API (different order, no query). Do not reuse the Merchant API implementation.

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

Every POST requires a JSON object body; send {} when there are no fields (an empty body returns 400 invalid_json). Authentication errors are 401 (partner_not_authorized / stale_timestamp / invalid_nonce / invalid_signature), a reused nonce is 409 replayed_nonce, and a non-allow-listed IP is 403 ip_not_allowed.

From instruction to credit

Amounts are in USD. Both source_asset and destination_asset are required and must match. Only MATCHMOVEUSD-to-MATCHMOVEUSD can be funded; USD-to-USD and SGP-USD-to-SGP-USD can be created but are rejected by /fund. Cross-asset conversion is prohibited.

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":"...", ...}

Prerequisites: an approved Partner bound to the Merchant, an APPROVED and ACTIVE/FULL beneficiary, the corporate_payout Connected App scope, and a Merchant-enabled payout policy (per-payout and daily limit, UTC day) in SAKURA Merchant console → “V-REC Corporate Payout”. Without it /fund returns RETRYABLE (corporate_payout_policy_not_enabled).

Over a limit: /fund returns RETRYABLE (corporate_payout_merchant_approval_required) and SAKURA queues an approval request. After the Merchant approves it in SAKURA (valid 24 hours), confirm fund_retry_permitted=true via GET /approval-status, then call /fund for the same payout. If it is not approved you can /cancel.

Full parameters, responses and error codes: Payout OpenAPI →

SAKURA remains authoritative; V-REC exposes guarded Merchant operations

V-REC does not maintain an independent authoritative Tenant available balance. Use balance/capacity to read SAKURA-authoritative state, then execute either direct allocation or payout-based funding. New money movement is allowed only for an ACTIVE/FULL membership whose source Merchant equals the Tenant Merchant. READONLY may still read masked card metadata, but cannot receive new Tenant funds.

Current funding requires more than the V-REC tenant_funding.read/write HMAC permission: existing SAKURA Connected Apps must be explicitly reauthorized for tenant_funding and checked for exact Merchant/origin/program binding, ENFORCED, api_execute_enabled and reconciliation state. Missing grants or READONLY membership block new allocations.

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.

Expiry (including a 180-day policy where applicable) is stored on the V-REC lot from the effective SAKURA snapshot returned at allocation execution. Viewing, spending or returning the lot does not restart the expiry period.

SAKURA /api/integrations/vrec/tenant-funding/* remains an internal Connected Apps API. External Merchants must use /api/merchant/v1/tenant-funding/* instead of calling the SAKURA integration endpoints directly.

Current public API boundaries

There is no direct Merchant fund endpoint. User payout instructions are created through the Partner Payout API. Operator-granted Merchant credentials may issue VIRTUAL cards, but do not receive PAN/CVV. Cardholders must enter their V-REC password into a short-lived one-time hosted V-REC page to view sensitive details. An explicitly granted cards.manage Merchant credential can freeze/unfreeze cards, but cannot access PIN or PAN/CVV.