BVNK

Architecture: payments, channels & virtual accounts

BVNK bridges bank rails and stablecoin chains behind one RESTful merchant API (JSON over HTTPS, Hawk auth). The primitives compose into payin/payout flows.

• Payment: an IN or OUT object carrying a quoted FX rate and an expiry; hosted flow returns a redirectUrl, merchant-hosted routes inline with payout details.
• Channel: a reusable address/route an end user pays into repeatedly, tagged with per-customer compliance/originator metadata (api/v2/channel).
• Virtual accounts: named GBP/EUR accounts wired to major payment schemes for fiat payin/payout.
• Webhooks (x-signature, HMAC-SHA256) are the source of truth for status — payment, channel, crypto, customer, ledger events.

Layer1 & the self-custody settlement model

Layer1 inverts the usual custodial model: instead of BVNK holding funds, the enterprise runs its own stablecoin network and BVNK provides orchestration only — so BVNK is explicitly not in the flow of funds.

• Enterprise controls wallets, keys, integrations, reconciliation, and data.
• Modular, payments-first orchestration: omnibus wallets, automated consolidation, multi-venue trading, Digital Asset Engine.
• Smart Treasury adds predictive, AI-powered, 24/7 liquidity management across chains/wallets/venues.
• Elliptic supplies risk intelligence to keep self-managed settlement compliant.

Visa Direct partnership & the Mastercard acquisition

BVNK moved from card-network partner to card-network asset within roughly a year — a signal of how strategic stablecoin rails became to the networks.

• Visa Ventures invested in BVNK (May 2025); BVNK then powers stablecoin payouts for Visa Direct pilots (enterprises pre-fund in stablecoins, recipients get wallet payouts).
• Citi Ventures took a stake (Oct 2025), pushing valuation above the prior ~$750M.
• Coinbase reportedly neared a ~$2B acquisition before talks ended around Nov 2025.
• Mastercard agreed to acquire BVNK for up to $1.8B (~$300M contingent), announced Mar 2026 — the largest stablecoin deal to date, eclipsing Stripe/Bridge ($1.1B).

Compliance & licensing footprint

BVNK's moat is heavily regulatory: a broad, multi-jurisdiction license stack underpins enterprise trust and the network partnerships.

• US: registered MSB with FinCEN + state money transmitter (or equivalent) licenses (NMLS ID 2531294).
• UK/EU: two EMI licenses — UK FCA (via the 2022 SPS acquisition) and Malta — plus a VASP registration.
• Malta MiCA CASP licence secured Feb 2026, passported across the EU.
• 25+ authorizations in total; compliance/KYC/sanctions screening embedded in payin/channel flows.

Architecture

BVNK sits between bank rails (for fiat payin/payout and virtual accounts) and stablecoin chains, exposing one RESTful merchant API over HTTPS with JSON. Core primitives are the Payment (an IN or OUT object with a quoted FX rate and an expiry), the Channel (a reusable address/route an end user can pay into repeatedly), and the Wallet (fiat + stablecoin balances). For custodial products BVNK holds keys and is in the flow of funds; for Layer1, the enterprise self-custodies and BVNK only provides orchestration. State changes are delivered via signed webhooks, which are the source of truth — the client/redirect is not.

Integration shape

Authenticate with Hawk auth (an API key ID + secret you generate in the Merchant Portal) over a sandbox (api.sandbox.bvnk.com) then production base URL. Two main collection patterns: hosted — create a payment and redirect the customer to BVNK's returned redirectUrl to finish; or merchant-hosted — quote currencies/protocols yourself and supply payout details so funds route with no redirect. Reusable inbound flows use Channels. Verify every webhook's x-signature (HMAC-SHA256 over the raw JSON body) before acting.

API surface

POST /api/v1/pay/summary

Create a payment summary — an incoming (IN) or outgoing (OUT) crypto payment with a quoted rate; returns a redirectUrl unless payout details are supplied inline.

PUT /api/v1/pay/{uuid}/update/summary

Select the pay currency/protocol on an existing payment summary to lock the quote. [verify exact path]

GET /api/v1/pay/{uuid}

Read a payment's current status and details (poll fallback to webhooks).

POST /api/v2/channel

Create a Channel — a reusable address/route end users pay into, with payCurrency, displayCurrency, reference, customerId, and compliance/originator details.

GET /api/v2/channel/{id}

Read a channel and its associated payments (channelPaymentRead).

POST payout (fiat/crypto)

Create a payout to a bank account (EUR/GBP) or wallet/address; settles from your merchant balance or wallet.

Webhooks (x-signature, HMAC-SHA256)

Subscribe to payment, channel, crypto, customer, and ledger status events; verify signature over the raw payload.

Minimal integration

Create a crypto payin via the merchant API, then verify the status webhook (Hawk auth + HMAC-SHA256).

import crypto from 'node:crypto';

// 1) Create an incoming payment (hosted flow returns a redirectUrl).
const res = await fetch('https://api.sandbox.bvnk.com/api/v1/pay/summary', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    // Hawk auth header derived from your API key id + secret:
    Authorization: hawkHeader(BVNK_KEY_ID, BVNK_SECRET, 'POST', '/api/v1/pay/summary'),
  },
  body: JSON.stringify({
    merchantId: BVNK_MERCHANT_ID,
    type: 'IN',
    displayCurrency: { currency: 'EUR' },
    walletCurrency: 'USDC',
    reference: 'order-123',
  }),
});
const payment = await res.json();
// Redirect the customer to payment.redirectUrl to complete the pay-in.

// 2) Webhook handler — treat the webhook, NOT the redirect, as source of truth.
function handleWebhook(rawBody: string, headers: Record<string, string>) {
  const expected = crypto
    .createHmac('sha256', BVNK_WEBHOOK_SECRET)
    .update(rawBody) // raw JSON, unparsed
    .digest('hex');
  if (headers['x-signature'] !== expected) throw new Error('bad signature');
  const event = JSON.parse(rawBody); // { status: 'COMPLETE' | 'EXPIRED' | ... }
  // reconcile order-123 against event.status
}

Build notes

• Hawk auth signs each request with your key id + secret; quotes on a payment expire, so lock the pay currency/protocol promptly and handle EXPIRED.
• Always build against the sandbox base URL first; switch host + keys for production.
• Webhook signature is HMAC-SHA256 over the raw, unparsed body — verify before JSON.parse, and idempotently reconcile by your own reference.
• [verify exact endpoint paths, versions (v1 pay vs v2 channel), and field names against the live docs.bvnk.com reference.]