Configure which customer fields appear on the hosted checkout page, name, email, phone, and optionally bind the link to an existing customerId. Videpay creates or updates customer records and attaches them to payments and webhooks. Collect what you need; skip the 47-field survey nobody finishes.
Need machine-readable request/response bodies for your AI or codebase? Download this page as plain Markdown.
You pass customerId on the checkout link for returning members. New members leave email required on the hosted page: Videpay creates a customer, sends customer.created, and every payment.settled includes customer.id for your database sync.
Set collectCustomer* on the request to show fields on the hosted page; requireCustomer* to make them mandatory. The response uses customerCollection.collectEmail style: names differ between request and response.
| Field | Type | Required | Description |
|---|---|---|---|
customerId | uuid | No | Pre-bind checkout to an existing customer. Skips creating a duplicate when the buyer is already in your CRM. |
collectCustomerName / requireCustomerName | boolean | No | Show and optionally require name on hosted checkout. |
collectCustomerEmail / requireCustomerEmail | boolean | No | Show and optionally require email: typical for receipts. |
collectCustomerPhoneNumber / requireCustomerPhoneNumber | boolean | No | Show and optionally require phone number. |
/checkout-linksCheckout with all customer fields enabled; bound to existing customerId.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "title": "Member renewal",03 "asset": "USDC",04 "chain": "base",05 "mode": "one_time",06 "amount": "99",07 "customerId": ":cus_3b7e9f1a-2c4d-5e6f-7a8b-9c0d1e2f3a4b",08 "collectCustomerName": true,09 "requireCustomerName": true,10 "collectCustomerEmail": true,11 "requireCustomerEmail": true,12 "collectCustomerPhoneNumber": true,13 "requireCustomerPhoneNumber": false14}When a customer pays via deposit address, they can submit name, email, and phone on POST .../deposit-sessions. These populate the session customer and may create a new CRM record.
| 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. |
payment.settled and deposit.* webhooks include the customer object when available. Use customer.reference to map back to your database. New customers also trigger customer.created from the Customers API.
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...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...