Most integrators never call smart contracts directly — Videpay's REST API and relayer handle on-chain work for you. This page explains what happens on-chain so you can answer security reviewers, trace a settlement on a block explorer, and connect API responses like `transaction.hash` to real contract behavior.
Need machine-readable request/response bodies for your AI or codebase? Download this page as plain Markdown.
When should I use this?
Your security or compliance team asks where customer funds go during checkout.
You need to verify a **`payment.settled`** webhook against a block explorer.
You audit fee deduction, payout routing, or non-custodial guarantees for due diligence.
You debug a failed settlement and want to know which contract reverted and why.
Why use Videpay?
Transparent settlement: every completed payment includes an on-chain **`transaction.hash`** you can inspect.
Non-custodial: Videpay never holds merchant private keys; settlement goes to your registered wallet or **AccountWallet**.
Your security team asks where customer USDC goes during checkout. You explain: the customer sends USDC to **PaymentSettlement** (or a deterministic deposit contract the relayer sweeps). The contract checks **MerchantRegistry** and **TokenRegistry**, deducts the platform fee to treasury, then forwards net funds to your registered settlement address — or to **PayoutRouter** if an active split rule exists. You paste **`transaction.hash`** from the API into BaseScan. You sound extremely prepared. You are.
See Supported chains for which networks and assets are enabled in your environment.
Checkout and settlement API details live on Checkout and Payments.
How the stack fits together
Videpay is a hybrid system: merchants integrate with the REST API; the backend relayer submits transactions to protocol contracts on your behalf. You do not deploy contracts or manage relayer keys — Videpay runs protocol deployments per chain and environment (sandbox testnets vs live mainnets).
You integrate with the API, not the contracts
Contract ABIs and direct `eth_call` usage are for auditors and advanced debugging. Normal integrations use REST endpoints, webhooks, and block explorers to verify `transaction.hash`.
Your app creates checkout links, deposit sessions, transfers, and other resources via authenticated HTTP.
Videpay backend validates business rules, builds calldata, and submits transactions through an approved relayer address.
Webhooks + API responses return `transaction.hash`, amounts, and status so your systems stay in sync with chain finality.
Where money goes (standard checkout)
Exact paths vary by product (deposit address, virtual wallet, escrow, subscription), but a typical USDC checkout looks like this:
Customer pays USDC on the chosen chain (direct `pay()`, signed relay intent, or transfer to a deposit / virtual wallet the relayer sweeps).
PaymentSettlement (or the sweep target) validates the merchant is Active in MerchantRegistry and the token is enabled in TokenRegistry.
Platform fee is deducted per the operation's fee bucket in TokenRegistry; fee goes to the protocol treasury.
Net amount is forwarded to your registered settlement address (EOA or AccountWallet).
If you have an active payout rule, net funds go to PayoutRouter, which splits to configured recipients in one transaction.
The backend emits `payment.settled` (and related events) with `transaction.hash` for your records.
Core protocol contracts
These singletons are deployed once per chain per environment. Addresses differ between sandbox and live — your dashboard and API responses include the chain context; do not hardcode mainnet addresses in sandbox.
TokenRegistry — accepted tokens, oracle/USD pricing, treasury address, and per-operation fee rates (payment, transfer, escrow, subscription, etc.). Source of truth for "is this asset supported?" and "what fee applies?"
MerchantRegistry — on-chain merchant identity keyed by settlement wallet. Stores status (Active / Suspended), profile hash, and registration metadata. Other contracts call `assertActive(merchant)` before settling.
PaymentSettlement — standard checkout settlement: customer payment in, fee out, net to merchant (or PayoutRouter). Supports direct and relayed (EIP-712) payment intents.
DepositAddress + DepositAddressFactory — deterministic one-off deposit contracts for wallet-free checkout; relayer sweeps when funds arrive.
CustomerVirtualWallet + CustomerVirtualWalletFactory — reusable customer receiving addresses (same `walletId` → same address across chains when factories use matching CREATE2 salts).
ReconciliationLedger — on-chain checkpoints for operational reconciliation (backend-coordinated; useful for audit trails).
Finance & payout contracts
PayoutRouter — post-settlement revenue splits. When a merchant registers an active rule, PaymentSettlement forwards net funds here instead of a single wallet.
TransferManager — outbound merchant payouts and batch transfers with merchant consent (delegated approval, not a signature per transfer).
RecipientRegistry — on-chain recipient lists used by payout and transfer flows.
SubscriptionManager — recurring billing: plan charges, dunning, and cancellation enforced on-chain.
Escrow — lock USDC until release, dispute resolution, or expiry; arbiters (operations-approved) resolve disputes.
ProgrammablePayments — vesting, time locks, and threshold-based releases (separate from immediate share splits).
DonationWallet + DonationWalletFactory — campaign wallets with deterministic addresses per `walletId`.
Merchant smart wallets
Merchants can settle to an EOA or to an AccountWallet — a smart contract wallet with guardian recovery, deployed deterministically via AccountWalletFactory.
Generic contract names
Core wallet contracts use protocol-neutral names (AccountWallet, ProtocolTimelock, ProtocolUUPSUpgradeable) so on-chain deployments are not tied to the Videpay product name. API and dashboard copy use "Videpay"; block explorers show the generic contract names.
AccountWalletFactory — CREATE2 factory; same `walletId` yields the same wallet address on every chain when factory + beacon salts match.
Registration still keys off the wallet address in MerchantRegistry — the API `settlementMode` and dashboard settings determine EOA vs AccountWallet.
Swap & cross-chain (optional modules)
When enabled for your environment, swap flows use separate router contracts. The API orchestrates quotes and execution; you still receive standard payment/settlement webhooks for the overall operation.
CrossChainSwap + bridge adapters (e.g. Stargate) — cross-chain routes under unified API requests.
See Swap and Cross-chain swap for API usage; contracts enforce slippage and deadline parameters you pass.
Governance, upgrades & pause
Production deployments split authority across three on-chain roles. On sandbox testnets these often collapse to the deployer — fine for development, not for production.
pauseGuardian — emergency pause on sensitive contracts without config control.
Protocol singletons use UUPS upgradeable proxies; child wallets use BeaconProxy for implementation upgrades without changing child addresses.
Same address on every chain
Four factory systems produce deterministic child addresses from a logical id (`walletId`, `depositId`, etc.). When the same factory address and salt are used on Base, Polygon, and other supported chains, the resulting deposit or wallet address matches. This lets hosted checkout and wallet display stay chain-aware while the identity stays global.
AccountWalletFactory — merchant/customer smart wallets from `walletId`.
DepositAddressFactory — one-off checkout deposits from `depositId` + refund address.
Contract addresses and merchant registrations are environment-specific. A transaction on Base Sepolia proves sandbox behavior only — register again on live mainnet before accepting real funds.
Complete a sandbox checkout or wait for a live `payment.settled` webhook.
Copy `transaction.hash` from the API response or webhook payload.
Open the chain's block explorer (BaseScan, PolygonScan, etc.) and paste the hash.
Inspect token transfers: customer → settlement path, treasury fee line item, net to merchant or PayoutRouter recipients.
Match `amount`, `asset`, and `chain` in the webhook to the explorer's ERC-20 transfer events.
What the API returns
Settlement responses and webhooks include enough context to audit without reading contract source. Typical fields:
Field
Type
Required
Description
transaction.hash
string
Yes
On-chain transaction hash. Paste into the chain block explorer.
transaction.chainId
integer
No
EVM chain id (e.g. 8453 Base, 137 Polygon).
amount / amountUsd
string
No
Human-readable settled amount; compare to Transfer events in the tx.
feeBps / feeAmount
string | integer
No
Platform fee applied at settlement; rates live in TokenRegistry.
merchantAddress
address
No
Registered settlement wallet from MerchantRegistry.
GET/payments/{id}
Example settled payment envelope (fields vary by payment method).