VidepayDocumentation

Customers

Customers are buyer profiles in Videpay. Create them via API or let checkout auto-collect details, then attach customerId to checkout links, subscriptions, and deposit sessions so every payment maps back to a person in your system. CRM hygiene, but the payments team will actually use it.

Need machine-readable request/response bodies for your AI or codebase? Download this page as plain Markdown.

When should I use this?

You have a CRM or user database and want payments tied to customer records.
Repeat buyers should be recognized across checkout sessions and subscriptions.
You issue receipts, invoices, or support lookups per customer.

Why use Videpay?

reference field maps Videpay customers to your database IDs.
Attach customers to checkout links, subscriptions, and virtual wallets.
Full lifecycle webhooks: created, updated, and archive.
Dashboard Customers tab mirrors the API.

CRM-linked payments

When a user signs up in your app (user_12345), you create an Videpay customer with reference: user_12345. Every checkout, subscription, and virtual wallet deposit links back to that CRM record via customerId. One ID to rule the reconciliation spreadsheet.

Before you start

Secret API key with business access
Webhook endpoint for customer.created / customer.updated / customer.archive

How customers work

Create a customer with name and optional email, reference, and metadata.
Pass customerId when creating checkout links, subscriptions, or deposit sessions.
Checkout can also auto-create customers when collectCustomerEmail is enabled.
PATCH to update details; DELETE archives (soft delete): archived customers are excluded from list by default.
Archived customers cannot receive new virtual wallets but existing wallets continue working.

Dashboard features

Dashboard → Customers

The Customers tab lists all active records with search, pagination, and detail views. Create customers, edit fields, archive records, and open the Virtual wallets sub-tab to deploy deposit addresses, all actions map to the endpoints below.

Search by name, email, or reference.
View linked payments, subscriptions, and virtual wallets from customer detail.
Archive customers you no longer need: emits customer.archive.

Create a customer

Field	Type	Required	Description
`businessId`	`uuid`	No	Target business. Omit when your API key is scoped to one business.
`name`	`string`	Yes	Customer display name (max 120 characters).
`email`	`string`	No	Optional email for receipts and checkout collection.
`phoneNumber`	`string`	No	Optional phone number (max 30).
`reference`	`string`	No	Your CRM or user ID: unique per business. Used to link payments and subscriptions.
`notes`	`string`	No	Internal notes (max 500). Not shown to customers.
`metadata`	`object`	No	Arbitrary JSON stored on the customer record.

POST/customers

Create a customer record. Emits customer.created.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

Request body

request.json

01{02  "name": "Jane Doe",03  "email": "customer@example.com",04  "phoneNumber": "+15551234567",05  "reference": "user_12345",06  "notes": "Premium tier",07  "metadata": {08    "tier": "pro"09  }10}

List and retrieve customers

Field	Type	Required	Description
`businessId`	`uuid`	No	Target business. Omit when your API key is scoped to one business.
`q`	`string`	No	Search filter: matches name, email, or reference.
`offset / limit`	`integer`	No	Pagination. limit is 1–100, default 20.
`includeArchived`	`integer`	No	Set to 1 to include archived customers in list results.

GET/customers?q=jane&limit=20&offset=0

List customers with pagination. Search by name, email, or reference via q.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

GET/customers/:cus_3b7e9f1a-2c4d-5e6f-7a8b-9c0d1e2f3a4b

Retrieve a single customer by ID.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

Update and archive

Field	Type	Required	Description
`businessId`	`uuid`	No	Target business. Omit when your API key is scoped to one business.
`email`	`string`	No	Optional email for receipts and checkout collection.
`phoneNumber`	`string`	No	Optional phone number (max 30).
`reference`	`string`	No	Your CRM or user ID: unique per business. Used to link payments and subscriptions.
`notes`	`string`	No	Internal notes (max 500). Not shown to customers.
`metadata`	`object`	No	Arbitrary JSON stored on the customer record.
`name`	`string`	No	Updated display name.
`email / phoneNumber / reference / notes`	`string \| null`	No	Send null to clear optional fields.
`metadata`	`object \| null`	No	Send null to clear metadata.

PATCH/customers/:cus_3b7e9f1a-2c4d-5e6f-7a8b-9c0d1e2f3a4b

Update customer fields. At least one field required. Emits customer.updated.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

Request body

request.json

01{02  "name": "Jane D.",03  "notes": "Updated tier"04}

DELETE/customers/:cus_3b7e9f1a-2c4d-5e6f-7a8b-9c0d1e2f3a4b

Archive a customer (soft delete). Emits customer.archive. Idempotent if already archived.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

Customer in payment and subscription webhooks

When you attach customerId to checkout links, deposit sessions, subscriptions, or settlement payments, every related webhook carries the CRM record so you can fulfill orders without a follow-up GET. Hosted checkout can also create customers mid-flow: later deposit.updated and payment.settled events include the collected identity.

customer is null when no customerId was set and checkout has not collected buyer details yet.
customer.created fires when checkout auto-creates a new buyer record.
Archived customers serialize as null on payment payloads: re-link or use an active record.

Field	Type	Required	Description
`customer`	`object \| null`	No	Linked CRM customer when customerId was set at creation or checkout collected buyer identity. Always present on deposit sessions, settlement payments, and subscriptions: null when unlinked. Shape: { id, name, email, phoneNumber, reference }.
`id`	`uuid`	No	Videpay customer record ID.
`name`	`string`	No	Display name.
`email / phoneNumber`	`string \| null`	No	Contact fields when collected.
`reference`	`string \| null`	No	Your CRM or user ID: unique per business.
`deposit.* / payment.*`	`path`	No	data.deposit.customer or data.payment.customer on all settlement webhooks.
`subscription.*`	`path`	No	data.subscription.customer on lifecycle and charge events.
`customer.dedicated-virtual-wallet.*`	`path`	No	data.customer on virtual wallet deploy, deposit, sweep, and recovery events.

Customer object reference

Field	Type	Required	Description
`id`	`uuid`	No	Videpay customer record ID.
`name / email / phoneNumber`	`string`	No	Contact and display fields.
`reference`	`string`	No	Your CRM ID: unique per business.
`notes / metadata`	`string / object`	No	Internal notes and arbitrary JSON.
`status`	`enum`	No	active or archived.
`archivedAt`	`datetime`	No	Set when status is archived; null otherwise.

Webhooks you'll receive

Register a webhook endpoint and verify the X-Protocol-Signature header on every delivery before fulfilling orders or updating your database.

Webhookcustomer.created

Sent when a new customer record is created.

Delivery headers

webhook-headers

01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: customer.created04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...

Webhookcustomer.updated

Sent when customer details change via PATCH /customers/:id.

Delivery headers

webhook-headers

01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: customer.updated04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...

Webhookcustomer.archive

Sent when a customer is archived (soft-deleted) via DELETE /customers/:id.

Delivery headers

webhook-headers

01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: customer.archive04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...

← Donations Virtual wallets →