# Vivamo API Documentation

> Vivamo is a payment compliance and orchestration platform. The API handles customer management, payment collection, disbursements (payouts), KYC identity verification, and webhook notifications. All endpoints require Bearer token authentication. Base URLs: api.vivamo.co (production), api.test.vivamo.co (sandbox).

## Guides

- [Introduction](https://docs.vivamo.co/index.mdx): Overview of the Vivamo platform, integration flow, and getting started.
- [Authorization](https://docs.vivamo.co/guides/authorization.mdx): How to authenticate with the API using secret and publishable keys.
- [Environment Setup](https://docs.vivamo.co/guides/environment-setup.mdx): Configuring development and production environments, including mock transaction testing.
- [Customers](https://docs.vivamo.co/guides/customers.mdx): Creating and managing customer records. Required before payment or disbursement flows.
- [KYC Verification](https://docs.vivamo.co/guides/kyc-verification.mdx): Identity verification flow, status tracking, and manual review.
- [Payments](https://docs.vivamo.co/guides/payments.mdx): Four-stage payment intent flow: create intent, pass clientSecretKey to SDK, process, receive result.
- [Disbursements](https://docs.vivamo.co/guides/disbursements.mdx): Payout flow with manual approval step before funds are sent.
- [Vivamo SDK](https://docs.vivamo.co/guides/vivamo-sdk.mdx): Frontend SDK for embedding payment and disbursement flows with a single script tag.
- [Webhooks](https://docs.vivamo.co/guides/webhooks.mdx): Registering endpoints, verifying HMAC-SHA512 signatures, and handling event payloads.
- [Error Handling](https://docs.vivamo.co/guides/error-handling.mdx): HTTP status codes, error response format, and common error messages.
- [Personal Tax](https://docs.vivamo.co/guides/personal-tax.mdx): W-9 collection, 1099 reporting ($2,000 YTD disbursement threshold), and W-2G prize filing (bingo $1,200+, horse racing $600+ at 300x wager).
- [Geolocation](https://docs.vivamo.co/guides/geolocation.mdx): Location-based transaction restrictions and pre-checking customer IP addresses before presenting payment UI.
- [Go-Live Checklist](https://docs.vivamo.co/guides/go-live-checklist.mdx): Pre-production checklist covering account setup, customer integration, payments, disbursements, KYC, webhooks, geolocation, error handling, testing, and approval requirements.

## API Reference - Customers

- [POST /v1/customers - Create Customer](https://docs.vivamo.co/api/create-customer): Create a new customer record. Minimum fields: externalCustomerId and data.email. Returns 400 if a customer with the same externalCustomerId or email already exists.
- [GET /v1/customers - List Customers](https://docs.vivamo.co/api/list-customers): Retrieve a paginated list of customer records. Supports page and size query parameters.
- [GET /v1/customers/{externalCustomerId} - Get Customer](https://docs.vivamo.co/api/get-customer): Retrieve a customer record by externalCustomerId, including profile data and KYC verification history.
- [PUT /v1/customers/{externalCustomerId}/data - Update Customer](https://docs.vivamo.co/api/update-customer): Update a customer's profile fields. All fields are optional.

## API Reference - KYC Verification

- [GET /v1/customers/{externalCustomerId}/kyc-info - Get KYC Info](https://docs.vivamo.co/api/get-customer-kyc-info): Retrieve KYC verification status and links. Expired links (1-hour TTL) are regenerated automatically.
- [POST /v1/customers/{externalCustomerId}/kyc-verify/{type} - Set KYC Manually Verified](https://docs.vivamo.co/api/set-customer-kyc-manually-verified): Approve or reject a customer's KYC verification when status is under_review.
- [GET /v1/customers/kyc-for-review - Get Customers With KYC For Review](https://docs.vivamo.co/api/get-customers-with-kyc-for-review): List all customers with KYC submissions in under_review status.

## API Reference - Payments

- [POST /v1/payment-intents - Create Payment Intent](https://docs.vivamo.co/api/create-payment-intent): Create a payment intent. Returns a clientSecretKey to pass to the SDK. Requires amount, currency, and externalPaymentIntentId. Intents expire after 2 hours.
- [GET /v1/payment-intents/{paymentIntentId}/status - Get Payment Intent Status](https://docs.vivamo.co/api/get-payment-intent-status): Retrieve intent status (no-payment, pending, success, failed) and individual payment attempts.

## API Reference - Disbursements

- [POST /v1/disbursement-intents - Create Disbursement Intent](https://docs.vivamo.co/api/create-disbursement-intent): Create a disbursement intent. Returns a clientSecretKey to pass to the SDK. Disbursements require manual approval before processing. Intents expire after 2 hours.
- [GET /v1/disbursement-intents/{disbursementIntentId}/status - Get Disbursement Intent Status](https://docs.vivamo.co/api/get-disbursement-intent-status): Retrieve intent status (pending-validation, pending, success, failed, rejected) and the disbursement record.
- [GET /v1/disbursements/pending-validation - Get Disbursements Awaiting Approval](https://docs.vivamo.co/api/get-disbursements-awaiting-approval): List all disbursements in pending-validation status awaiting your approval.
- [POST /v1/disbursements/{disbursementIntentId}/proceed/{allow} - Proceed With Disbursement](https://docs.vivamo.co/api/proceed-with-disbursement): Approve (allow=true) or reject (allow=false) a pending disbursement. Approved disbursements are sent for processing immediately.

## API Reference - Prizes (W-2G)

- [POST /v1/customers/{externalCustomerId}/prizes - Record Prize](https://docs.vivamo.co/api/record-prize): Record a qualifying gambling prize for W-2G filing. Validates against IRS thresholds by tax type (bingo: $1,200+, horse racing: $600+ and 300x wager). Returns w9CaptureUrl if the customer hasn't completed a W-9.
- [GET /v1/customers/{externalCustomerId}/prizes - Get Customer Prizes](https://docs.vivamo.co/api/get-customer-prizes): List a customer's prize records. Defaults to current calendar year. Supports taxYear query parameter.

## API Reference - Geolocation

- [POST /v1/operators/check-geolocation - Check Geolocation](https://docs.vivamo.co/api/check-geolocation): Pre-check whether a customer's IP address is in an allowed geolocation for this operator. Returns allowed status with country and state details. Skips IP lookup if no location rules are configured.

## API Reference - Webhooks

- [POST /v1/operators/webhooks - Register Webhook](https://docs.vivamo.co/api/register-webhook): Register a webhook URL. Returns a one-time HMAC-SHA512 secret key for signature verification.
- [GET /v1/operators/webhooks - List Webhooks](https://docs.vivamo.co/api/list-webhooks): Retrieve all registered webhook endpoints.
- [DELETE /v1/operators/webhooks - Delete Webhook](https://docs.vivamo.co/api/delete-webhook): Remove a registered webhook endpoint.

## Object Schemas

- [CustomerData](https://docs.vivamo.co/api/objects/CustomerData): Customer profile fields. Only email is required.
- [Customer](https://docs.vivamo.co/api/objects/Customer): Full customer record with profile data and KYC verification history.
- [KycVerification](https://docs.vivamo.co/api/objects/KycVerification): KYC verification record with type, status (pending, verified, under_review, rejected, expired, verified_manually, rejected_manually), and timestamps.
- [Payment](https://docs.vivamo.co/api/objects/Payment): Individual payment attempt with status (pending, success, failed), type (card, bank, pay_by_bank, crypto), and messages.
- [Disbursement](https://docs.vivamo.co/api/objects/Disbursement): Individual disbursement record with status (pending-validation, pending, success, failed) and type.
- [PrizeRecord](https://docs.vivamo.co/api/objects/PrizeRecord): W-2G prize record with IRS box fields, tax year, status (recorded, submitted, filed), and wager details.
- [CustomData](https://docs.vivamo.co/api/objects/CustomData): Up to 3 custom key-value pairs for attaching metadata to intents.
- [ErrorResponse](https://docs.vivamo.co/api/objects/ErrorResponse): Standard error response with message, optional errorCode, and optional validation errors array.

## Optional

- [OpenAPI Spec](https://docs.vivamo.co/openapi.yaml): Full OpenAPI 3.0 specification with all endpoints, request/response schemas, and examples.
- [AI & LLM Support](https://docs.vivamo.co/support/ai-and-llms.mdx): How to use these docs with LLMs and AI coding assistants.
- [Release Notes](https://docs.vivamo.co/support/release-notes.mdx): Changelog of API, SDK, and documentation updates.