A Checkout Link is a secure payment page you send to customers. You create it once via the API, share checkoutUrl, and Videpay handles address generation, on-chain detection, fees, and settlement. No Solidity required on your side: your backend can stay in TypeScript peace.
Need machine-readable request/response bodies for your AI or codebase? Download this page as plain Markdown.
A customer completes a $49.99 cart. Your server creates a checkout link with line items and order metadata, emails checkoutUrl, and listens for payment.settled (or the same event over Realtime) to mark the order paid and start fulfillment. Polling every 3 seconds is officially a side quest you can skip.
Use amount for a single fixed price. Set feeBearer to customer if the payer covers the protocol fee (total increases), or merchant if you absorb it.
/checkout-linksMinimal fixed-amount checkout: 25 USDC, email required, redirects after payment. Accepts public or secret API keys.
01x-api-key: pk_AbCdEfGhIj_XyZ1234567890abcdefghij02Content-Type: application/json01{02 "title": "Videpay Pro Plan",03 "asset": "USDC",04 "chain": "base",05 "mode": "one_time",06 "amount": "25",07 "feeBearer": "customer",08 "collectCustomerEmail": true,09 "requireCustomerEmail": true,10 "settledRedirectUrl": "https://yourapp.com/success",11 "cancelRedirectUrl": "https://yourapp.com/cancel"12}Every field supported by POST /checkout-links. Use items instead of amount for multi-line carts (up to 50 line items). Request fields use collectCustomer* names; response uses customerCollection.collectEmail style.
/checkout-linksComplete example with line items, customer collection, fee bearer, redirects, expiry, and metadata.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "title": "Summer Collection Checkout",03 "description": "Pay for your order in USDC. Funds settle instantly on-chain.",04 "reference": "order-2026-1042",05 "customPath": "summer-drop",06 "asset": "USDC",07 "chain": "base",08 "mode": "one_time",09 "amount": "49.99",10 "feeBearer": "customer",11 "customerId": null,12 "collectCustomerName": true,13 "requireCustomerName": false,14 "collectCustomerEmail": true,15 "requireCustomerEmail": true,16 "collectCustomerPhoneNumber": true,17 "requireCustomerPhoneNumber": false,18 "settledRedirectUrl": "https://yourapp.com/checkout/success?ref=order-2026-1042",19 "cancelRedirectUrl": "https://yourapp.com/checkout/cancel?ref=order-2026-1042",20 "expiresAt": "2026-08-07T23:59:59.000Z",21 "metadata": {22 "orderId": "ord_1042",23 "campaign": "summer-2026"24 },25 "items": [26 {27 "name": "Videpay Pro: 1 month",28 "description": "Full platform access",29 "quantity": 1,30 "unitAmount": "29.99"31 },32 {33 "name": "Priority support add-on",34 "description": "24h response SLA",35 "quantity": 1,36 "unitAmount": "20.00"37 }38 ]39}Required: title, asset, mode. Provide either amount (fixed price) or items (line-item cart), not both as primary pricing. Omit chain to let customers pay on any network your business supports: otherwise lock to a single chain. Request fields use collectCustomer* names; responses use customerCollection.collectEmail style.
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Checkout page title shown to the customer. |
description | string | No | Optional subtitle on the hosted checkout page. |
reference | string | No | Your order ID: echoed in webhooks and payments for reconciliation. |
customPath | string | No | Vanity path segment for checkoutUrl (e.g. summer-drop → /pay/summer-drop). |
asset | string | Yes | Payment asset symbol. USDC in sandbox. DAI, BUSD, USDT, USDC, EURC, and cNGN in live. |
chain | string | No | Lock checkout to one chain (e.g. base, polygon). Omit to let the customer pay on any network your business is registered on that supports the asset: the hosted page lists those networks in supportedChains. See Supported chains. |
mode | enum | Yes | one_time (single payment) or reusable (multiple payments on the same link). |
amount | decimal string | No | Fixed price when not using line items. Sets pricing.type to fixed. |
items[] | array | No | Line-item cart (max 50). Each item: name, description?, quantity, unitAmount. Sets pricing.type to line_items. |
feeBearer | enum | No | merchant (you absorb protocol fee) or customer (fee added to total). |
customerId | uuid | No | Pre-link checkout to an existing customer record. |
collectCustomerName / requireCustomerName | boolean | No | Show and optionally require customer name on the hosted page. |
collectCustomerEmail / requireCustomerEmail | boolean | No | Show and optionally require email on the hosted page. |
collectCustomerPhoneNumber / requireCustomerPhoneNumber | boolean | No | Show and optionally require phone on the hosted page. |
settledRedirectUrl / cancelRedirectUrl | url | No | Redirect URLs after successful payment or cancellation. |
expiresAt | datetime | No | ISO datetime when the link stops accepting payments. |
metadata | object | No | Arbitrary JSON stored on the link and passed through to payments. |
/checkout-links/cl_7f3a9b2c-4d1e-4a8f-9c0b-1e2d3f4a5b6cGet a single checkout link with pricing, items, and customerCollection.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json/checkout-links?status=active&limit=20List checkout links with optional filters: status, mode, customerId, q (search).
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json/checkout-links/cl_7f3a9b2c-4d1e-4a8f-9c0b-1e2d3f4a5b6cUpdate title, redirects, customer collection flags, status, or metadata.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "title": "Updated checkout title",03 "settledRedirectUrl": "https://yourapp.com/new-success",04 "status": "active"05}Register a webhook endpoint and verify the X-Protocol-Signature header on every delivery before fulfilling orders or updating your database.
checkout.createdSent when you create a new checkout link.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: checkout.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.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...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...