> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vitawallet.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Payout

> Send funds from your business wallet to a bank account in any supported country.

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.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> 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.

> [!WARNING]
>
> **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.

> [!NOTE]
>
> **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.

> [tab] AR — Individual
>
> Argentina, individual beneficiary, settled in USD from a USD-denominated amount destination.
>
> ```json theme={null}
> {
>   "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/"
> }
> ```

> [tab] AR — Business
>
> Argentina, corporate beneficiary, sent in ARS from a fixed source amount.
>
> ```json theme={null}
> {
>   "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/"
> }
> ```

> [tab] CL — Business Final Customer
>
> Chile (CLP), with the **Final Customer service** enabled — note the `fc_` fields describing the real initiator of the transaction (in this case, a company).
>
> ```json theme={null}
> {
>   "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"
> }
> ```

> [tab] EU — SWIFT + Final Customer
>
> European Union (IBAN + SWIFT/BIC), with a natural Final Customer. International payouts typically require more fields (city, phone, zipcode, state).
>
> ```json theme={null}
> {
>   "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"
> }
> ```

> [tab] AR — Natural Final Customer
>
> Argentina with Final Customer enabled — the beneficiary is a corporate entity, and the real initiator (`fc_`) is a natural person.
>
> ```json theme={null}
> {
>   "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"
> }
> ```

> [!NOTE]
>
> **`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)

```json theme={null}
{
  "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

> [accordion] Error 304 — Missing parameter
>
> A field required by `/withdrawal_rules` for this country is missing.
>
> ```json theme={null}
> {
>   "error": {
>     "code": 304,
>     "message": "Parameter document_number not found",
>     "action_required": "Provide parameter document_number"
>   }
> }
> ```

> [accordion] Error 305 — Double amount
>
> `amount` and `amount_destination` cannot both be greater than zero.
>
> ```json theme={null}
> {
>   "error": {
>     "code": 305,
>     "message": "It is not possible to send both amounts, only one is allowed"
>   }
> }
> ```

> [accordion] Error 305 — Invalid format
>
> A field value does not match the required format returned by `/withdrawal_rules`.
>
> ```json theme={null}
> {
>   "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"
>     }
>   }
> }
> ```

> [accordion] Error 500 — Invalid amount / below minimum
>
> ```json theme={null}
> {
>   "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"
>     }
>   }
> }
> ```

> [accordion] Error 500 — Insufficient funds
>
> ```json theme={null}
> {
>   "error": {
>     "code": 500,
>     "message": "Error creating vita transaction",
>     "details": {
>       "title": "Balance insuficiente",
>       "message": "La transacción no pudo ser procesada por insuficiencia de fondos"
>     }
>   }
> }
> ```

> [accordion] Error 502 — No exchange rate available
>
> Call `GET /api/businesses/prices` to refresh rates before retrying.
>
> ```json theme={null}
> {
>   "error": {
>     "code": 502,
>     "message": "No exchange rate available",
>     "required_action": "GET payouts prices"
>   }
> }
> ```

## Idempotency & timeout handling

**1. Submit with a long timeout**

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

**2. 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.

**3. Query by order**

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

**4. 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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.