Create Payout

Create Payout

curl --request POST \
  --url https://api.vitawallet.io/api/businesses/transactions

const options = {method: 'POST'};

fetch('https://api.vitawallet.io/api/businesses/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vitawallet.io/api/businesses/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vitawallet.io/api/businesses/transactions"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.vitawallet.io/api/businesses/transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

api

businesses

transactions

Create Payout

curl --request POST \
  --url https://api.vitawallet.io/api/businesses/transactions

const options = {method: 'POST'};

fetch('https://api.vitawallet.io/api/businesses/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vitawallet.io/api/businesses/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vitawallet.io/api/businesses/transactions"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.vitawallet.io/api/businesses/transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

Send funds from your business wallet to a bank account in any country supported by Vita. The amount is deducted from your source wallet and credited to the beneficiary’s bank account through the destination country’s banking rails.

Dynamic fields. The fields required to create a payout vary by destination country. Call GET /api/businesses/withdrawal_rules before creating the transaction to retrieve the exact fields and validation rules for the destination you’re sending to.

This endpoint shares its URL with the other transaction creation flows. The transactions_type field is the discriminator — set it to "withdrawal" for a bank payout.

Concurrent requests are serialized, not rate-limited. Vita processes each business’s payouts one at a time. If you submit multiple POST /transactions calls in parallel for the same account, the later ones wait in queue — they are not rejected. Configure your HTTP client with a generous timeout (60–90s+) and rely on order for idempotency, not on response time.

Final Customers service. If your account has Final Customers enabled, include the additional fields prefixed with fc_ describing the person or business actually initiating the transaction. The required fields are returned by /withdrawal_rules.

Request structure

Key	Description
`transactions_type`	Must be `"withdrawal"`.
`country`	ISO country code of the destination (e.g. `"CO"`, `"MX"`, `"CL"`).
`currency`	Source currency (must be active in your wallet).
`amount`	Amount to send in the source currency. Send `0` if you use `amount_destination`.
`amount_destination`	Amount to receive in the destination currency. When > 0, `amount` must be `0`.
`order`	Unique order identifier. Critical for idempotency.
`wallet`	Origin wallet (UUID; `"master"` by default).
`purpose`	Purpose code (required by some countries — see Purpose Codes documentation).
`purpose_comentary`	Free-text comment / MEMO describing the transaction purpose.
`url_notify`	URL for legacy IPN notifications (use Webhooks instead when possible).

Beneficiary and (optional) Final Customer fields are returned dynamically by /withdrawal_rules and vary per country.

Request examples by destination

Each destination country has its own required fields (returned by /withdrawal_rules). The following tabs show real payloads for the most common destinations.

AR — Individual
AR — Business
CL — Business Final Customer
EU — SWIFT + Final Customer
AR — Natural Final Customer

Argentina, individual beneficiary, settled in USD from a USD-denominated amount destination.

{
  "transactions_type": "withdrawal",
  "country": "AR",
  "currency": "usd",
  "amount": 0,
  "amount_destination": 5000,
  "order": "0001234",
  "wallet": "2408444c-d2ed-4dce-982f-462db9be822c",
  "beneficiary_type": "Individual",
  "beneficiary_first_name": "Carlos",
  "beneficiary_last_name": "Garcia",
  "beneficiary_email": "carlos.garcia@example.com",
  "beneficiary_address": "Av. Corrientes 1234, Buenos Aires",
  "beneficiary_document_type": "CUIL",
  "beneficiary_document_number": "20123456789",
  "bank_code": "97",
  "account_type_bank": "S",
  "account_bank": "0720010088000012345678",
  "purpose": "ISSUPP",
  "purpose_comentary": "Pago de proveedor local",
  "url_notify": "https://my_business.com/"
}

Argentina, corporate beneficiary, sent in ARS from a fixed source amount.

{
  "transactions_type": "withdrawal",
  "country": "AR",
  "currency": "ars",
  "amount": 1000,
  "amount_destination": 0,
  "order": "0003a",
  "wallet": "2408444c-d2ed-4dce-982f-462db9be822c",
  "beneficiary_type": "Corporate",
  "company_name": "Empresa Ejemplo SA",
  "beneficiary_email": "contacto@empresa-ejemplo.com",
  "beneficiary_address": "Av. Corrientes 1234, Buenos Aires",
  "beneficiary_document_type": "CUIT",
  "beneficiary_document_number": "30123456789",
  "bank_code": "97",
  "account_type_bank": "C",
  "account_bank": "0720010088000012345678",
  "purpose": "ISSUPP",
  "purpose_comentary": "Pago de proveedor local",
  "url_notify": "https://my_business.com/"
}

Chile (CLP), with the Final Customer service enabled — note the fc_ fields describing the real initiator of the transaction (in this case, a company).

{
  "transactions_type": "withdrawal",
  "country": "CL",
  "currency": "clp",
  "amount": 100000,
  "order": "0002",
  "wallet": "a6c44ea8-cba1-40e9-839a-1348a5701108",
  "beneficiary_first_name": "Gabriela",
  "beneficiary_last_name": "Pazmiño",
  "beneficiary_email": "my_email@vitawallet.io",
  "beneficiary_address": "My address, esquina, 21-64",
  "beneficiary_document_type": "RUT",
  "beneficiary_document_number": "111111",
  "account_type_bank": "Cuenta de ahorros",
  "account_bank": "999999999",
  "bank_code": 10,
  "purpose": "ISSAVG",
  "purpose_comentary": "This is a test",
  "url_notify": "https://my_business.com/",
  "fc_customer_type": "business",
  "fc_legal_name": "Google LLC",
  "fc_trade_name": "Google",
  "fc_tax_id": "X0101010101",
  "fc_legal_address": "My address, 10-20, US"
}

European Union (IBAN + SWIFT/BIC), with a natural Final Customer. International payouts typically require more fields (city, phone, zipcode, state).

{
  "transactions_type": "withdrawal",
  "country": "EU",
  "currency": "usd",
  "amount": 0,
  "amount_destination": 100,
  "order": "0003a676556555",
  "wallet": "2408444c-d2ed-4dce-982f-462db9be822c",
  "beneficiary_type": "Individual",
  "beneficiary_first_name": "Hans",
  "beneficiary_last_name": "Muller",
  "beneficiary_email": "finance@example-gmbh.de",
  "beneficiary_address": "Unter den Linden 1, Berlin",
  "city": "Berlin",
  "phone": "4930123456",
  "beneficiary_document_type": "DNI",
  "beneficiary_document_number": "L1234567B",
  "account_type_bank": "Checking",
  "account_bank": "DE89370400440532013000",
  "swift_bic": "DEUTDEDB",
  "purpose": "ISSUPP",
  "purpose_comentary": "Pago de proveedor",
  "url_notify": "https://my_business.com/",
  "fc_customer_type": "natural",
  "fc_legal_name": "Juan Carlos Ejemplo",
  "fc_document_type": "dni",
  "fc_document_number": "12345678",
  "fc_legal_address": "Av. Ejemplo 1234, Ciudad",
  "fc_birthdate": "1990-05-15",
  "fc_residence_country": "AR",
  "fc_city": "Buenos Aires",
  "fc_state": "Buenos Aires",
  "fc_zipcode": "1000"
}

Argentina with Final Customer enabled — the beneficiary is a corporate entity, and the real initiator (fc_) is a natural person.

{
  "transactions_type": "withdrawal",
  "country": "AR",
  "currency": "usd",
  "amount": 0,
  "amount_destination": 5000,
  "order": "0003a1234",
  "wallet": "2408444c-d2ed-4dce-982f-462db9be822c",
  "beneficiary_type": "Corporate",
  "company_name": "Empresa Ejemplo SA",
  "beneficiary_email": "contacto@empresa-ejemplo.com",
  "beneficiary_address": "Av. Corrientes 1234, Buenos Aires",
  "beneficiary_document_type": "CUIT",
  "beneficiary_document_number": "30123456789",
  "bank_code": "97",
  "account_type_bank": "C",
  "account_bank": "0720010088000012345678",
  "purpose": "ISSUPP",
  "purpose_comentary": "Pago de proveedor local",
  "url_notify": "https://my_business.com/",
  "fc_customer_type": "natural",
  "fc_legal_name": "Nombre completo",
  "fc_document_type": "dni",
  "fc_document_number": "132425273",
  "fc_legal_address": "Domicilio completo",
  "fc_birthdate": "1990-01-01",
  "fc_residence_country": "BO"
}

amount vs amount_destination. Send exactly one of these with a value greater than zero. The other must be 0 (or omitted). amount is denominated in currency (source); amount_destination is denominated in the destination country’s local currency.

Response — Success (201)

{
  "transaction": {
    "id": "4fc5e05d-443e-4302-b320-f5fe6cf8edf1-77550",
    "type": "business_transaction",
    "attributes": {
      "status": "checking",
      "currency": "usd",
      "amount": "5.64",
      "total": "5.64",
      "created_at": "2026-05-28T14:12:30.032Z",
      "order": "0001234",
      "category": "withdrawal",
      "included": {
        "withdrawal": {
          "country_iso_code": "AR",
          "country_name": "Argentina",
          "currency": "ars",
          "total_without_fixed_cost": "5350.0",
          "total_sent": "5000.0",
          "fixed_cost": "350.0",
          "sell_price": "947.6",
          "bank_account": {
            "first_name": "Carlos",
            "last_name": "Garcia",
            "address": "Av. Corrientes 1234, Buenos Aires",
            "email": "carlos.garcia@example.com",
            "beneficiary_type": "individual"
          },
          "reject_motive": null
        }
      },
      "vita_transaction_id": "4fc5e05d-443e-4302-b320-f5fe6cf8edf1-77550",
      "tracking_url": "https://tracking.vitawallet.io/..."
    }
  }
}

Common errors

Error 304 — Missing parameter

A field required by /withdrawal_rules for this country is missing.

{
  "error": {
    "code": 304,
    "message": "Parameter document_number not found",
    "action_required": "Provide parameter document_number"
  }
}

Error 305 — Double amount

amount and amount_destination cannot both be greater than zero.

{
  "error": {
    "code": 305,
    "message": "It is not possible to send both amounts, only one is allowed"
  }
}

Error 305 — Invalid format

A field value does not match the required format returned by /withdrawal_rules.

{
  "error": {
    "code": 305,
    "message": "beneficiary_last_name: the value does not match the required format",
    "details": {
      "message": "Solo se permiten letras y números",
      "field": "last_name",
      "api_parameter": "beneficiary_last_name"
    }
  }
}

Error 500 — Invalid amount / below minimum

{
  "error": {
    "code": 500,
    "message": "Error creating vita transaction",
    "details": {
      "message": "Monto no válido, debes ingresar un monto igual o superior al monto mínimo"
    }
  }
}

Error 500 — Insufficient funds

{
  "error": {
    "code": 500,
    "message": "Error creating vita transaction",
    "details": {
      "title": "Balance insuficiente",
      "message": "La transacción no pudo ser procesada por insuficiencia de fondos"
    }
  }
}

Error 502 — No exchange rate available

Call GET /api/businesses/prices to refresh rates before retrying.

{
  "error": {
    "code": 502,
    "message": "No exchange rate available",
    "required_action": "GET payouts prices"
  }
}

Idempotency & timeout handling

Submit with a long timeout

Use a client timeout of 60–90s+. Vita’s queue takes a few extra seconds under load.

On timeout or 500, do NOT retry with a new order

The order field is your idempotency key. Reusing it protects you from duplicates; replacing it does not.

Query by order

GET /api/businesses/transactions?order=<your_order_id> to find out whether the payout was actually created.

Resolve

If found → save the Vita transaction ID and continue. If not found → safely retry the original POST with the same order.

Test environment — automated status resolution

In test environments only, include a keyword in purpose_comentary to auto-complete or auto-deny the transaction:

Keyword	Behavior
`COMPLETED`	Transaction is automatically processed as completed.
`REJECTED`	Transaction is automatically processed as denied.

Keywords must match exactly (including capitalization). Status change is reflected within 0–15 minutes. This mechanism does not apply in production.

Quick recap

GET /api/businesses/withdrawal_rules → fields required for the destination country.
GET /api/businesses/prices → rates to calculate the final amount.
(Optional) POST /api/businesses/beneficiaries/validate_beneficiary → confirm identifier-based recipients (PIX, Bre-B, CLABE, IBAN, ABA).
Generate a unique order ID.
POST /api/businesses/transactions with transactions_type: "withdrawal" and a generous timeout.
On timeout → query by order before retrying; never reuse with a new order.

Payins

Exchange

Payouts

Transactions

Users

Webhooks

Request structure

Request examples by destination

Response — Success (201)

Common errors

Idempotency & timeout handling

Test environment — automated status resolution

Quick recap

​Request structure

​Request examples by destination

​Response — Success (201)

​Common errors

​Idempotency & timeout handling

​Test environment — automated status resolution

​Quick recap

Request structure

Request examples by destination

Response — Success (201)

Common errors

Idempotency & timeout handling

Test environment — automated status resolution

Quick recap