---
title: AI integration prompt
icon: sparkles
hidden: true
description: A prompt for AI coding assistants that sets out how to integrate Vivamo correctly and which pages to read at each step.
---

# AI integration prompt

:::subtitle
Instructions for an AI coding assistant integrating Vivamo
:::

<Callout>
  This page is written for an AI coding assistant. To use it, paste the one-line prompt from the [Introduction](/) into your assistant, or give it this page's markdown version: https://docs.vivamo.co/guides/ai-integration-prompt.mdx
</Callout>

You are adding Vivamo to this application. Vivamo is a payment compliance and orchestration platform for gaming operators. It handles customer records, payments, payouts (called disbursements), KYC identity verification, geolocation checks, US personal tax collection and webhook notifications.

The integration has two halves. The backend calls the Vivamo API with a secret key. The frontend mounts the Vivamo SDK, which renders every screen the customer sees.

Build against the sandbox. Do not point anything at production.

## The documentation is the source of truth

This prompt tells you how to integrate Vivamo correctly. It deliberately contains no code, request bodies, endpoint paths, field names, status or event values, hostnames or test values, because those change. Take every one of them from the current documentation at https://docs.vivamo.co.

- Start from the index at https://docs.vivamo.co/llms.txt. It links every guide and API reference page.
- Every guide is available as markdown: add `.mdx` to its path, as in https://docs.vivamo.co/guides/payments.mdx.
- Request and response schemas, required fields and every status value are in the OpenAPI spec at https://docs.vivamo.co/openapi.yaml.
- Each step below names the pages to read. Read them at the start of that step, not from memory or from what you may already know about Vivamo.
- If you can't fetch web pages, stop and ask the developer to paste the pages each step names.
- Copy values from the docs exactly. Keep each set of status values and event names in one constant or enum in the codebase, so a documentation change means a single edit.
- If two pages disagree, or the API rejects a request that follows the docs, stop and tell the developer which pages conflict and what you saw. Don't pick one quietly, and don't guess a workaround.

## Ground rules

These rules are what make an integration correct. Follow them even where the documentation's examples, the codebase or your own habits suggest otherwise.

1. The secret key stays on the backend. It must never reach the browser, a mobile bundle, logs, error messages, analytics or source control. The frontend only ever sees the publishable key and the per-intent client secret the API returns for the SDK.
2. Read keys from environment variables or the project's existing secret manager. Do not open, print or edit `.env` files or any file that holds real credentials. Tell the developer which variables to set and let them fill in the values.
3. The SDK is the only customer-facing integration path. Do not build your own payment form, bank linking, phone verification, KYC capture, tax form, fee breakdown or location prompt, because the SDK already does all of them. Do not hide, restyle away or disable any SDK element, including fee breakdowns, payment method selectors and informational notices.
4. Never decide a transaction's outcome in the browser. An SDK event tells you a flow has ended, not that it succeeded. Credit a deposit or settle a payout only from a verified webhook or a server-side status call.
5. A payout moves no money until the operator approves it through the API. Do not add automatic approval unless the developer gives you the exact business rules for it.
6. Send every amount in exactly the type and format the API reference gives for that endpoint. The formats are not the same across endpoints. Never do floating-point arithmetic on money.
7. Do not use anything the documentation marks as deprecated or legacy, including the legacy KYC paths in the KYC guide.
8. Two outcomes are easy to misread as final failures, and neither is:
   - An intent that expires before the customer submits a payment or requests a payout was never attempted. It is not a failed transaction. The status endpoints report this with their own expiry value, which the API reference lists. Close it out as expired.
   - Only the statuses the KYC guide defines as verified, whether automatic or manual, mean a customer has passed KYC. Every other KYC status, rejected included, can still change, and a rejected customer can later become verified through a manual decision. Never close or permanently block an account because of a KYC status.
9. Do not invent endpoints, fields, statuses or event names. If the documentation doesn't cover something you need, ask the developer.

## Step 1: Look before you write

Read: https://docs.vivamo.co/llms.txt and https://docs.vivamo.co/index.mdx

Inspect the codebase and work out:

- the backend language and framework, and how it makes outbound HTTP calls
- the frontend framework, and how it loads third-party scripts
- how users are identified, and which stable internal user ID will become the customer's external ID in Vivamo
- where deposits, withdrawals or orders are modelled, and how player balances change
- how configuration and secrets are loaded
- whether there is an admin area or back office

Then ask the developer these questions and wait for the answers before writing code:

1. Which flows do you need: payments (deposits), payouts (disbursements), or both?
2. Do you want customers verified before they ever reach a payment or payout, for example at signup? If not, the SDK runs KYC automatically on the first transaction and there is nothing to build.
3. Which personal tax type did Vivamo configure for you during onboarding, if any? The Personal Tax guide explains which types need code.
4. Who approves payouts, and how? A person in your back office, or automated rules you can state exactly?
5. When is a player's balance debited for a payout: when they request it, or when it succeeds? What happens to it if the payout is rejected, fails, is declined or its intent expires?
6. Which public HTTPS URL will receive webhooks in the sandbox?

Present a short plan, listing the files you will add or change and why, and wait for the developer to confirm it.

## Step 2: Configuration

Read: https://docs.vivamo.co/guides/authorization.mdx and https://docs.vivamo.co/guides/environment-setup.mdx

- Take the sandbox and production API hosts, the SDK script source for each environment, and the SDK's environment option from Environment Setup.
- Each environment has its own keys. Suggested settings: `VIVAMO_API_BASE_URL`, `VIVAMO_SECRET_KEY` (backend only), `VIVAMO_PUBLISHABLE_KEY`, `VIVAMO_SDK_URL`, `VIVAMO_SDK_ENVIRONMENT` and `VIVAMO_WEBHOOK_SECRET` (backend only).
- Default every value to the sandbox. Moving to production must be a configuration change, with no code edits.

## Step 3: Backend API client

Read: https://docs.vivamo.co/guides/authorization.mdx and https://docs.vivamo.co/guides/error-handling.mdx

Write one small client module that every Vivamo call goes through.

- Authenticate every request as the Authorization guide describes, over HTTPS only.
- Parse errors as the Error Handling guide describes. Surface the message, and map validation errors to the fields they name.
- Retry read requests on server errors with exponential backoff. Do not retry a request that creates an intent automatically: Vivamo does not deduplicate your intent references, so a blind retry can create a second intent.
- Never log the secret key, a client secret or the webhook secret.

## Step 4: Customers

Read: https://docs.vivamo.co/guides/customers.mdx and the Create Customer and Update Customer API reference pages

- Every payment or payout needs a Vivamo customer record first. Create it at signup, or just before the customer's first transaction.
- Use your stable internal user ID as the customer's external ID.
- Send every profile field you already hold. The SDK pre-fills from them, so customers see fewer prompts, and tax reporting needs no extra step.
- Make creation idempotent. The Error Handling guide lists the error returned when the customer already exists for your operator; treat it as success and carry on.
- When the API rejects an email address or phone number, show the error to the user. Don't quietly rewrite their details to get past it.
- When a user edits their profile in your app, send the change to Vivamo.

## Step 5: Payments (deposits)

Read: https://docs.vivamo.co/guides/payments.mdx and the Create Payment Intent and Get Payment Intent Status API reference pages

The flow: your backend creates a payment intent, the frontend mounts the SDK with the intent's client secret, the customer pays inside the SDK, and your backend learns the outcome from a webhook or the status endpoint.

- Create intents from an authenticated backend endpoint. Take the customer from the logged-in session, never from the request body.
- Give every intent a new, unique reference of your own. Vivamo does not enforce uniqueness, so your code has to.
- Store your reference and Vivamo's intent ID together, with the user, amount and currency, before you respond. Webhooks and the status endpoint don't identify the payment the same way; the docs say which ID each one uses.
- Return only the client secret, and your own reference if the frontend needs it, to the browser.
- Intents expire; the Payments guide gives the window. Create a fresh intent for each checkout attempt, and never cache one or reuse it across sessions.
- Check the amount against your own limits on the server. Don't trust an amount from the browser.
- Handle every intent status in the Get Payment Intent Status reference. Each attempt's own status and failure reason are in the response too.

Expiry is not failure:

- An intent that expires without a payment is an abandoned checkout. Don't mark the order as failed or declined, and don't tell the customer their payment failed. Close it out as expired, and create a new intent if they come back.
- Don't wait for a webhook to tell you an intent expired. To close out abandoned checkouts, check the status endpoint once the intent's expiration time has passed.
- Expiry only stops new payments against the intent. A payment submitted before it can still settle afterwards, as a bank payment can, and the status then reports success. Never cancel or refund an order just because its intent's expiration time has passed.

## Step 6: The SDK (frontend)

Read: https://docs.vivamo.co/guides/vivamo-sdk.mdx

- Load the SDK script for the current environment and initialise it with the publishable key and the environment option, exactly as the SDK guide shows.
- Create one instance per page, after the script has loaded. In single-page apps, mount once the container element exists and don't create a new instance on every render. With server-side rendering, run SDK code in the browser only.
- Mount payments and payouts with the call the SDK guide gives; the SDK works out which flow to render from the client secret.
- Listen only for the events the SDK guide lists, with the payloads it documents. Don't listen for an event the guide doesn't list. Payouts, for example, are tracked through webhooks rather than an SDK completion event.
- When the payment flow ends, call your backend for the outcome and route the user from that. Bank payments can stay pending for days, so show a "processing" state for a pending payment rather than a failure.
- The location events are for logging only. The SDK has already shown the customer what is happening.
- If the app sets a Content Security Policy, ask the developer to confirm the origins the SDK needs with Vivamo support rather than guessing them.
- Check the SDK guide's browser support section before you promise support for a browser.

## Step 7: Payouts (disbursements)

Skip this step if the developer only needs payments.

Read: https://docs.vivamo.co/guides/disbursements.mdx, https://docs.vivamo.co/guides/personal-tax.mdx and the disbursement API reference pages

The flow: your backend creates a disbursement intent, the customer picks a payout method and completes any verification in the SDK, the payout waits for your approval, you approve or reject it, Vivamo pays out, and webhooks report the result.

- The rules from payments apply: a unique reference of your own every time, stored with Vivamo's intent ID, and a fresh intent per request.
- Check that the player has the balance before creating the intent, and apply the balance rule the developer gave you.
- The intent may come back with personal tax details still to collect. You don't need to act on them, because the SDK collects missing details and the tax form itself.
- Show the player what they will receive. The Disbursements guide explains how fees affect the paid-out amount.

Approval:

- List the payouts waiting for a decision and approve or reject each one with the endpoints in the Disbursements guide.
- Build approval as an authenticated, permission-checked back-office action, or as the automated rule the developer specified. Record who decided and when. Players must never be able to reach it.
- Vivamo can enable auto-approve on an account, in which case the approval webhooks arrive without any action from you. Your code must work either way.

Expiry is not failure here either. A disbursement intent that expires before the customer requests the payout was never attempted. Release any balance you held for it under the developer's rule, and don't report a failure to the player. Expiry only stops new requests: a payout requested inside the window keeps its own status afterwards.

## Step 8: KYC

Read: https://docs.vivamo.co/guides/kyc-verification.mdx

- The default is SDK-enforced KYC, which needs no code. The SDK runs verification the first time a customer who needs it pays or requests a payout.
- Build the operator-initiated path in the KYC guide only if the developer wants customers verified up front. Fetch the customer's KYC info fresh each time you need it, and never cache the KYC client secret or the status.
- Treat only the statuses the guide defines as verified as a pass. No other status is final: a customer who is pending, under review, expired or rejected can become verified later. Don't close, ban or permanently flag an account because of a KYC status, and keep processing KYC webhooks for every customer, whatever their current status.
- Manual review happens in Vivamo Hub, not in your code. While a customer is under review they can't transact, and the decision reaches you as a webhook.
- A payout that triggers tax reporting needs a verified identity whatever the KYC settings. The SDK handles that too.

## Step 9: Personal tax

Read: https://docs.vivamo.co/guides/personal-tax.mdx

- Most tax types need no code. The SDK collects identity, name, address and the tax form.
- If the developer's tax type records prizes, record each qualifying prize when it is won, with the fields the guide requires for that type. Don't record prizes for any other tax type.
- Vivamo applies the IRS thresholds itself. A prize that doesn't qualify is rejected with a reason. Log it and don't retry.
- If a response includes a link for the customer to complete their tax form, showing it is optional. Don't store it, because it expires.

## Step 10: Geolocation pre-check (optional)

Read: https://docs.vivamo.co/guides/geolocation.mdx

Vivamo checks the customer's location on every SDK transaction. You can also check before showing payment UI, so a customer in a blocked location isn't left filling in a form that will be refused.

- Call the check from the backend. Take the customer's IP from the request using your proxy or CDN's trusted forwarded-for setting, never from a header the client controls.
- The answer is advisory. An allowed result doesn't guarantee the transaction will pass. When the result says the location isn't allowed, show a clear "not available in your location" message instead of the payment UI.
- When the check can't resolve the IP to a location (the guide describes that response), don't block the customer. Let the SDK establish their location.
- Location rules are set by Vivamo and can't be changed through the API.

## Step 11: Webhooks

Read: https://docs.vivamo.co/guides/webhooks.mdx and the webhook API reference pages

Webhooks are the reliable way to learn outcomes, especially for bank payments and payouts. Build the handler first, then register it.

The handler, in this order:

1. Read the raw request body bytes before any JSON parser touches them.
2. Verify the signature exactly as the Webhooks guide specifies (algorithm, header and encoding), computed over those raw bytes, and compare it in constant time. Reject the request if it doesn't match. Don't verify against re-serialised JSON. Re-encoding can change the bytes (by default Python's `json.dumps` adds spaces and PHP's `json_encode` escapes `/`), and the check then fails.
3. If you registered a custom header such as a pre-shared key, check that too.
4. Store the event and acknowledge it quickly, with the response the guide asks for. Do slow work asynchronously.
5. Make processing idempotent. Failed deliveries are retried (the guide gives the schedule), so the same event can arrive more than once.
6. Only move records forward, and never out of a terminal state, except where the guide documents a later status that can follow a success.
7. Acknowledge any event type you don't recognise without error.

Routing:

- Route by event type, and for transactions by transaction type, as the guide documents. Match each event to your records by your own reference.
- Handle every status the guide lists for each event. Statuses on webhooks can be spelt differently from the same statuses in API responses; the guide calls out where. Normalise them in one place.
- For KYC events, store whatever status arrives and treat anything other than a verified status as not verified yet. A customer you hold as rejected can later receive a verified status, so never ignore events for them.
- Tax form events are informational. Record them for reconciliation.

Registration happens once per environment, not on application start-up:

- Write a small script or CLI command the developer runs, using the Register Webhook endpoint with the request schema from the API reference.
- The signing secret is returned once only. Have the script print it a single time so the developer can put it in secret storage as `VIVAMO_WEBHOOK_SECRET`. Don't write it to a file in the repository.
- Register exactly one webhook endpoint per environment, subscribed to every event type you handle.
- Use the guide's update, list and delete endpoints for changes, and follow it to rotate the secret.

## Step 12: Test in the sandbox

Read: https://docs.vivamo.co/guides/environment-setup.mdx

- Use the sandbox test payment methods described in Environment Setup, if Vivamo has enabled them on your account. Some scenarios can't be reproduced in the sandbox.
- Write automated tests for the webhook handler (valid signature, invalid signature, duplicate delivery, every documented status, unknown event type) and for the API client's error handling. Build fixtures from the payloads in the docs, and don't call the real API from unit tests.
- Give the developer manual sandbox steps for a successful payment, a declined payment, a processing error, a payout that is approved and one that is rejected, a checkout left until its intent expires (which must end as expired, not failed), and a webhook with a tampered body, which must be refused.

## Step 13: Going live

Read: https://docs.vivamo.co/support/go-live-checklist.mdx

Walk the developer through the checklist. Production needs production keys from Vivamo, production configuration values, a webhook registered for the production URL with its own secret, and Vivamo's approval.

## When you finish

Give the developer:

- the files you added or changed
- the environment variables to set (names only, no values)
- the one-off webhook registration command
- the manual sandbox test steps
- the documentation pages you used
- anything you assumed, couldn't verify, or found inconsistent in the documentation
