Disbursements

Guides

Disbursements

Sending payouts to customers through the Vivamo platform

Disbursements allow you to send funds to your customers. Unlike payments, disbursements require your explicit approval before any funds are released.

Disbursement flow overview

A disbursement follows four stages:

Create a disbursement intent — Your backend creates an intent via the API, receiving a clientSecretKey.
Launch the SDK — The customer selects their preferred payout method and completes verification through the SDK.
Review and approve — The disbursement enters a pending-validation state. Your backend retrieves pending disbursements and either approves or rejects each one.
Processing and result — Once approved, Vivamo sends the funds through the appropriate processor and notifies you of the outcome via webhook.

Step 1: Create a disbursement intent

Use the Create Disbursement Intent endpoint from your backend to set up the customer and payout amount.

const response = await fetch("https://api.vivamo.co/v1/disbursement-intents", {
  method: "POST",
  headers: {
    Authorization: "Bearer your_secret_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer: {
      externalCustomerId: "user_123",
    },
    disbursementIntent: {
      amount: "50.00",
      currency: "USD",
      externalDisbursementIntentId: "payout_789",
      sendStatusEmail: true,
    },
  }),
});

The response includes:

clientSecretKey — Pass this to the SDK on your frontend. It authenticates the SDK session for this specific intent.
expirationTime — The intent expires 2 hours after creation. After this, the customer can no longer submit a payout method and you must create a new intent.
clientSecretKeyValidTill — The authentication window for the client secret (24 hours). In practice, the 2-hour intent expiration is the effective limit.

When sendStatusEmail is set to true, the customer receives email notifications at each stage of the disbursement.

Step 2: Launch the SDK

Pass the clientSecretKey to the Vivamo SDK on your frontend. The SDK handles payout method selection and any required customer verification. See the Vivamo SDK guide for setup instructions.

const vivamo = new Vivamo("pk_your_key");

vivamo.createElements("#disbursement-container", clientSecretKey);

Once the customer submits, the disbursement enters the pending-validation state and a webhook is sent to your backend. The SDK emits a disbursement-created event:

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

Step 3: Review and approve

Unlike payments, no funds are sent until you explicitly approve each disbursement.

Retrieve pending disbursements

Use the Get Pending Disbursements endpoint to retrieve all disbursements awaiting your approval:

const pending = await fetch(
  "https://api.vivamo.co/v1/disbursements/pending-validation",
  {
    headers: { Authorization: "Bearer your_secret_key" },
  }
);

The response includes customer details, the requested amount, payout method, and timestamps for each pending disbursement.

Approve or reject

For each disbursement, call the Proceed With Disbursement endpoint to either approve or reject it:

Approve:

await fetch(
  `https://api.vivamo.co/v1/disbursements/${disbursementIntentId}/proceed/true`,
  {
    method: "POST",
    headers: { Authorization: "Bearer your_secret_key" },
  }
);

Reject:

await fetch(
  `https://api.vivamo.co/v1/disbursements/${disbursementIntentId}/proceed/false`,
  {
    method: "POST",
    headers: { Authorization: "Bearer your_secret_key" },
  }
);

When approved, the disbursement is immediately sent for processing. When rejected, no funds are transferred and the customer is notified.

Step 4: Receive the result

Once a disbursement is approved and processed, Vivamo notifies you of the outcome via webhook. See the Webhooks guide for authentication and payload details.

You can also check the status at any time by calling the Get Disbursement Intent Status endpoint.

Disbursement statuses

Disbursements move through the following statuses:

Status	Description
`pending-validation`	The customer has submitted the disbursement and it is waiting for your approval.
`pending`	The disbursement has been approved and is being processed.
`success`	The funds have been sent successfully.
`failed`	Processing failed. A `subStatus` field provides further detail.
`rejected`	You rejected the disbursement during the approval step.

Supported payout methods

The available payout methods depend on your operator configuration. Vivamo supports:

Bank (ACH): standard bank account transfers.
Card: debit or prepaid card payouts.
Pay By Bank: instant ACH payouts via linked bank accounts.
Crypto: cryptocurrency payouts.

Amount format

The amount field should be a string in dollars and cents (e.g. "50.00", "9.99"). Amounts are stored and returned as strings throughout the API to avoid floating-point precision issues.

Key considerations

Disbursements will not be processed until you explicitly approve them. This gives you time to run fraud checks, verify account balances, or apply business rules before releasing funds.
Disbursement intents expire after 2 hours. If the customer does not complete the SDK flow in time, a new intent must be created.
The externalDisbursementIntentId field is for your own reference and is not enforced as unique. Submitting the same ID twice creates two separate intents. Use your own deduplication logic if needed.
Processing fees, if applicable, are subtracted from the payout amount. The customer receives the amount after fees.
When sendStatusEmail is enabled, the customer receives email updates when the disbursement is created, sent, or if it fails.
A webhook is sent at each status change: when the disbursement is created (pending-validation), when it succeeds, and if it fails. See the Webhooks guide.
See the Error Handling guide for error responses and status codes.

Payments Personal tax