Vivamo SDK

Guides

Vivamo SDK

Embed the Vivamo payment flow in your frontend

The Vivamo SDK renders payment forms, bank linking, phone verification, KYC prompts, and fee breakdowns. You load it via a script tag and point it at a container element.

Setup

Add the script to your page:

<script src="https://sdk.vivamo.co/v1" async></script>

Create a Vivamo instance with your publishable key:

const vivamo = new Vivamo("pk_your_key");

The publishable key must start with pk_. You receive this key alongside your secret key during onboarding.

The SDK enforces a singleton pattern. Calling new Vivamo() a second time returns the existing instance rather than creating a new one.

Configuration options

The Vivamo constructor accepts an optional second argument for configuration:

const vivamo = new Vivamo("pk_your_key", {
  environment: "test",
  customCss: "..." // optional full CSS replacement
});

Option	Type	Default	Description
`environment`	`string`	`"production"`	Set to `"test"` to use the sandbox environment.
`customCss`	`string`	`null`	Replaces the entire default stylesheet. See below.

Launching a payment or disbursement

From your backend, create a payment or disbursement intent via the API. Pass the returned clientSecretKey to the SDK:

vivamo.createElements(
  "#container", // CSS selector for the target element
  clientSecretKey
);

The SDK reads the intent type from the clientSecretKey and renders the appropriate flow — payment form or disbursement form. No additional configuration is needed to distinguish between them.

Launching the KYC flow

For operator-initiated KYC verification, fetch the customer's KYC info from Get Customer KYC Info and pass the returned clientSecretKey to createKycElements:

vivamo.createKycElements(
  "#container", // CSS selector for the target element
  clientSecretKey
);

The SDK renders the verification method picker (Driver's License or Passport), opens the chosen provider in a new tab, and polls for completion. Use this when you want a customer verified before they see a payment or disbursement form, for example at signup. See the KYC guide for the full story, including the SDK-enforced path where Vivamo launches the KYC flow automatically during a payment or disbursement.

Event listeners

The SDK emits events during the transaction lifecycle. Register listeners with vivamo.on():

vivamo.on("payment-created", (data) => {
  console.log("Payment submitted:", data);
});

vivamo.on("payment-completed", () => {
  // Payment has finished (success or timeout).
  // Fetch the intent status from your backend to confirm the outcome.
});

vivamo.on("disbursement-created", (data) => {
  console.log("Disbursement submitted:", data);
});

vivamo.on("kyc-completed", ({ status }) => {
  // status is "verified", "verified_manually", "rejected", or "expired"
});

Available events

Event	Data	When it fires
`payment-created`	Payment response object (`paymentId`, `status`)	After the customer submits a payment and the API accepts it.
`payment-completed`	None	When the payment reaches a final state (success or timeout).
`disbursement-created`	Disbursement response object (`disbursementId`, `status`)	After the customer submits a disbursement request.
`kyc-completed`	`{ status }`	When KYC finishes, with `status` set to `verified`, `verified_manually`, `rejected`, or `expired`.

There is no disbursement-completed event. Disbursements require your approval before processing, so the SDK flow ends when the disbursement enters pending-validation. Use webhooks to track the final outcome after you approve or reject it.

Recommended pattern

payment-completed tells you the SDK flow has ended, but does not include the payment status. Fetch the intent status from your backend when the event fires:

vivamo.on("payment-completed", async () => {
  const res = await fetch(`/api/payment-status/${paymentIntentId}`);
  const { status } = await res.json();

  if (status === "success") {
    window.location.href = "/payment/success";
  } else {
    window.location.href = "/payment/failed";
  }
});

Tax information form

If your operator has personal tax enabled and a customer's disbursement triggers the W-9, or there are existing W-2G prizes, the SDK handles the capture of tax information automatically.

The disbursement intent status endpoint will include a requires-tax-data status. You may present the w9CaptureUrl from the create disbursement intent response to the customer to preemptively have the customer complete this data, however this is not required. Poll the status endpoint until it returns created, then proceed with the normal flow.

What the SDK handles

The SDK manages the entire customer-facing flow: phone verification, KYC, W-9 tax forms, terms acceptance, payment method selection, fee breakdowns, and error states. You do not need to build UI for any of these.

Browser support

The SDK uses ES6+ features (async/await, Map, template literals, URL constructor) and does not support Internet Explorer.

Supported browsers: Chrome, Firefox, Safari, Edge (latest versions).

The SDK is built as a UMD bundle and can be loaded directly via a script tag in any modern browser.

Personal tax Webhooks