Documentation
Integration setup ↗

Authentication

Server integrations authenticate with a secret API key in the x-api-key header. Frontend-only integrations can use the public key (pk_...) for creating payments and polling status. Create keys in the dashboard, Settings → API Keys, not via a public API endpoint.

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

When should I use this?

  • You are calling Videpay from your backend, cron jobs, or serverless functions.
  • You need programmatic access without a logged-in dashboard session.

Why use Videpay?

  • API keys are scoped to a business and can be revoked instantly from the dashboard.
  • Sandbox and live keys are created on separate dashboards, no accidental cross-environment use.
  • No OAuth dance, one header on every request. Lowkey the best part.

Backend order fulfillment

You create a sandbox API key in the dashboard, store it as VIDEPAY_API_KEY, and call POST /checkout-links with x-api-key. When you go live, you create a new key on videpay.io and swap the env var, no application code changes.

Before you start

  • Account on https://sandbox.videpay.io (testing) or https://videpay.io (production)
  • Business created in the dashboard
  • Developer or Owner role with permission to manage API keys

Create your account

Sign up on the dashboard that matches your target environment: https://sandbox.videpay.io for sandbox integration, https://videpay.io for live. Verify your email, complete onboarding, and create your business from the dashboard wizard.

Create an API key

API keys are created only in the dashboard. The key you create inherits the environment of the dashboard you signed into: sandbox keys on https://sandbox.videpay.io, live keys on https://videpay.io.

  1. Sign in to https://sandbox.videpay.io (sandbox) or https://videpay.io (live).
  2. Open Settings → API Keys from the sidebar.
  3. Enter a descriptive name (e.g. "Local dev" or "Production backend").
  4. Choose a role: Developer is typical for integrations.
  5. Click Create API key.
  6. Copy the Secret key from the one-time modal immediately: Videpay cannot show it again.
  7. Optionally save the Public key (pk_...) for browser-safe integrations: create deposit sessions, checkout links, and poll payment status without a backend.

Store the secret securely

Treat the secret key like a password. Never commit it to git, never expose it in browser code, and load it from environment variables or a secrets manager. Future you (and your security reviewer) will send thanks.

  1. Add to your server as VIDEPAY_API_KEY (or your preferred env var name).
  2. Use separate keys for local development, staging, and production.
  3. Revoke compromised keys from Settings → API Keys → Revoke without redeploying code.

Use the key on every request

Send your API key in the x-api-key header (or x-public-key for pk_ keys). Sandbox requests go to https://sandbox.api.videpay.io. Live requests go to https://api.videpay.io. Secret keys look like sk_<keyId>_<secret>; public keys look like pk_<keyId>_<public>.

GET/finance/balances

Example authenticated request using a secret key in x-api-key.

Headers

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

Public key for frontend integrations

The public key is safe to embed in browser or mobile apps. Use it when you want to create payments and poll status without running your own server. Refunds, settlement sync, treasury operations, and listing all payments still require the secret key.

POST/payments/deposit-sessions

Create a deposit session from the browser using your public key.

Headers

headers
01x-api-key: pk_AbCdEfGhIj_XyZ1234567890abcdefghij02Content-Type: application/json

Request body

request.json
01{02  "asset": "USDC",03  "chain": "base",04  "amount": "10"05}
GET/payments/deposit-sessions/ds_...

Poll deposit session status (amounts.received, status, settlementPaymentId).

Headers

headers
01x-api-key: pk_AbCdEfGhIj_XyZ1234567890abcdefghij02Content-Type: application/json
GET/payments/settlements/pst_...

Poll wallet direct/intent settlement status and tx hash.

Headers

headers
01x-api-key: pk_AbCdEfGhIj_XyZ1234567890abcdefghij02Content-Type: application/json

Dashboard sessions vs API keys

The dashboard uses a logged-in browser session for UI actions. Your integration code uses API keys. Do not reuse dashboard session tokens for server automation: create a dedicated API key instead. Different tools, different quests.

← Integration setupEnvironments →