When a customer opens your checkout link, Videpay creates a deposit session with a unique USDC address per network. They send the exact amount from any wallet or exchange withdrawal. If you omitted chain when creating the link, the hosted page lists every chain your business supports and the customer picks one before paying. Multichain, but make it user-friendly.
Need machine-readable request/response bodies for your AI or codebase? Download this page as plain Markdown.
You email a checkout link for 500 USDC. Your client withdraws from Coinbase to the deposit address shown on the page. deposit.updated shows progress; payment.settled fires when the full amount is confirmed, you unlock the deliverable. No 'did you get my transfer?' Slack thread required.
Listen for payment.settled, not deposit.settled
deposit.created and deposit.updated track funding progress. When the full amount arrives and Videpay sweeps to your merchant wallet, a deposit_sweep settlement payment is created and payment.settled fires: there is no deposit.settled webhook.
Omit chain on create for all supported networks
When you do not pass chain on POST /checkout-links, Videpay sets chain.scope to all and returns supportedChains for every active merchant profile. The customer chooses a network on the hosted page; deposit session creation includes that chain. Pass chain at create time only when you want to restrict checkout to a single network.
| Field | Type | Required | Description |
|---|---|---|---|
name / email / phoneNumber | string | No | Customer identity collected on the hosted page. Stored on the session and used to create or update customer records. |
payerAddress | address | No | Wallet the customer intends to pay from (optional hint for reconciliation). |
refundAddress | address | No | Address to return funds if the session expires or is refunded. |
reference | string | No | Your order reference for this payment attempt. |
expiresInMinutes / expiresAt | integer / datetime | No | Session expiry: relative minutes (1–1440) or absolute ISO datetime. |
metadata | object | No | Arbitrary JSON attached to the deposit session. |
chain | string | No | Lock the session to one chain. Omit to create deposit routes on every active merchant chain that supports the asset: session.routes[] lists an address per network. An unsupported asset and chain combination returns 400. See Supported chains. |
/checkout-links/public/pub-k9m2x7/deposit-sessionsCalled by the hosted checkout page when a customer starts paying. No API key: public endpoint.
01Content-Type: application/json01{02 "name": "Jane Doe",03 "email": "buyer@example.com",04 "phoneNumber": "+15551234567",05 "payerAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",06 "refundAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",07 "reference": "order-1001",08 "expiresInMinutes": 60,09 "metadata": {10 "cartId": "cart_abc"11 }12}Create sessions from your backend when building a custom checkout UI that still uses deposit addresses. Same session shape as the public endpoint.
| Field | Type | Required | Description |
|---|---|---|---|
businessId | uuid | No | Target business. Omit when your API key is scoped to one business. |
chain | string | No | Lock the session to one chain. Omit to create deposit routes on every active merchant chain that supports the asset: session.routes[] lists an address per network. An unsupported asset and chain combination returns 400. See Supported chains. |
asset | string | Yes | Asset symbol from GET /finance/assets. When chain is omitted, routes are created on every active merchant chain that lists this symbol. |
amount | decimal string | Yes | Expected deposit amount: fixed for the life of the session. Partial and overpayment handling is relative to this total. |
refundAddress | address | No | Address to return overpayment change and expiry refunds. Required for correct excess handling on sweep. |
payerAddress | address | No | Expected sender wallet (optional enforcement hint). |
customerId | uuid | No | Attach session to a CRM customer. |
expiresAt | datetime | No | ISO datetime when the session stops accepting deposits. |
expiresInMinutes | integer | No | Relative expiry (1–1440 minutes) instead of expiresAt. |
reference / title / description / metadata | string / object | No | Reconciliation and display fields. |
/checkout-links/cl_7f3a9b2c-4d1e-4a8f-9c0b-1e2d3f4a5b6c/deposit-sessionsCreate a session from your backend: useful for custom checkout UIs that still use deposit addresses.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "customerId": ":cus_3b7e9f1a-2c4d-5e6f-7a8b-9c0d1e2f3a4b",03 "payerAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",04 "refundAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",05 "reference": "order-1001",06 "expiresInMinutes": 60,07 "metadata": {08 "source": "api"09 }10}/payments/deposit-sessions/ds_8e4f1a2b-3c5d-4e6f-7a8b-9c0d1e2f3a4bPoll session state: amounts.received, amounts.remaining, status.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json/payments/deposit-sessions/ds_8e4f1a2b-3c5d-4e6f-7a8b-9c0d1e2f3a4b/syncForce on-chain balance check if webhook was delayed.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json| Field | Type | Required | Description |
|---|---|---|---|
depositAddress | address | No | Unique address the customer sends USDC to. |
amounts.expected / amounts.received / amounts.remaining | string | No | Funding progress in human units. remaining hits zero when fully funded. |
amounts.progressPercentage | string | No | Percentage funded: useful for progress UI. |
status | enum | No | PENDING, PARTIALLY_FUNDED, FULLY_FUNDED, SETTLED, REFUNDED, EXPIRED, CANCELLED (uppercase in merchant API). |
settlementPaymentId | uuid | No | Linked settlement payment after sweep: present when status is SETTLED or REFUNDED. |
routes[] | array | No | When chain was omitted at create, one entry per supported merchant chain with its own depositAddress. |
customer | object | No | CRM customer when customerId was provided or identity collected on the page. |
/checkout-links/public/pub-k9m2x7/status?sessionId=ds_8e4f1a2b-3c5d-4e6f-7a8b-9c0d1e2f3a4bLightweight status for hosted pages. Prefer Realtime over polling in production: see Realtime events.
Register a webhook endpoint and verify the X-Protocol-Signature header on every delivery before fulfilling orders or updating your database.
deposit.createdSent when a deposit session is created and a unique payment address is assigned.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: deposit.created04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...deposit.updatedSent when deposit progress changes (partial payment received, balance sync, etc.). Not sent for terminal statuses.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: deposit.updated04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...payment.settledSent when funds are confirmed on-chain and credited to your merchant balance.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: payment.settled04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...