Disbursements
/
Create Disbursement Intent

Create Disbursement Intent

POST
https://api.vivamo.co/v1/disbursement-intents

Create a disbursement intent to pay out funds to a customer. Returns a clientSecretKey to pass to the Vivamo SDK. Requires amount, currency, and externalDisbursementIntentId. Intents expire after 2 hours. Disbursements require your manual approval before processing.

Request body

    customer
    object
    Required
      externalCustomerId
      string
      Required
      The customer identifier you provided when creating the record.
    disbursementIntent
    object
    Required
      externalDisbursementIntentId
      string
      Required
      Your reference identifier for this disbursement intent. Included in webhook payloads for reconciliation. Not enforced as unique — submitting the same ID twice creates separate intents.
      amount
      string
      Required

      Payout amount in dollars and cents (e.g. 50.00).

      currency
      string
      Required

      Currency code or crypto token (e.g. USD, CAD, USDT).

      customData
      object
      Up to 3 custom key-value pairs stored against the intent. Use these to attach your own metadata (e.g. order ID, invoice number).
      Examples:{"custom1":"value1","custom2":"value2","custom3":"value3"}
      sendStatusEmail
      boolean
      Defaults: false

      Set to true to send the customer email notifications at each stage of the disbursement.

Response

Disbursement intent created.
    disbursementIntentId
    string
    Vivamo's unique ID for this disbursement intent.
    amount
    string
    The disbursement amount.
    currency
    string
    The currency code.
    externalCustomerId
    string
    The customer identifier you provided.
    externalDisbursementIntentId
    string
    Your unique identifier for this disbursement intent.
    clientSecretKey
    string
    Secret key to pass to the Vivamo SDK.
    clientSecretKeyValidTill
    string

    Expiration time for the client secret key (24 hours). In practice, the 2-hour expirationTime is the effective limit.

    expirationTime
    string
    Expiration time for the disbursement intent. Intents expire after 2 hours.
    requiresCustomerData
    boolean

    Present and true when the operator has a personal tax type and this payout requires a W-9, but the customer is missing the name/address needed to register them for tax reporting. The SDK collects the missing fields before the W-9 step; the intent status is requires-customer-data. See the Personal Tax guide.

    missingCustomerDataFields
    array of string

    Present alongside requiresCustomerData. The customer fields still needed for tax reporting (e.g. street, city, state, zip).

    w9CaptureUrl
    string

    Present when the payout requires a W-9 and the customer's tax information is ready to collect (intent status requires-tax-data). A link to the hosted W-9 form; the SDK presents it automatically.

Built with