> ## 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.

# Marketplaces y plataformas

> Cobra a muchos compradores en su moneda y paga a muchos vendedores, incluso en otro país, con una sola integración.

Un marketplace cobra a muchos compradores en distintos países y paga a muchos vendedores, a veces en otra moneda. Con la API resuelves el ciclo completo — cobro, confirmación, conversión y payout — sin abrir cuentas locales en cada mercado.

## Flujo

```mermaid theme={null}
sequenceDiagram
  participant Buyer as Comprador
  participant App as Tu marketplace
  participant Vita as Vita API
  participant Seller as Vendedor

  Buyer->>App: Elige producto
  App->>Vita: POST /payment_orders
  Vita-->>App: payment_url
  Buyer->>Vita: Paga con método local
  Vita-->>App: Webhook payment_order.paid
  App->>App: Libera el pedido
  opt Conversión FX
    App->>Vita: POST /transactions (exchange)
  end
  App->>Vita: GET /prices + /withdrawal_rules
  App->>Vita: POST /transactions (withdrawal)
  Vita-->>Seller: Acreditación en banco
  Vita-->>App: Webhook transaction.completed
```

## Paso a paso

**1. Cobra al comprador en su moneda**

Crea una orden con `POST /payment_orders` (enlace de pago) o usa **Direct Payment** para mantener al comprador dentro de tu checkout. Consulta `GET /payment_methods/{país}` para mostrar solo los métodos disponibles en el país del comprador.

**2. Confirma el pago**

Escucha el webhook `payment_order.paid` y consulta `GET /payment_orders/:id` como respaldo. **Libera el pedido solo con el estado `paid`.**

**3. Convierte si hace falta**

Si cobras en moneda local y pagas en dólares, usa `POST /transactions` con `transactions_type: "exchange"` o configura el payin para que acredite directo en la moneda destino.

**4. Paga al vendedor**

`GET /prices` y `GET /withdrawal_rules` para el país del vendedor, y luego `POST /transactions` con `transactions_type: "withdrawal"`. Usa un `order` único por pago.

## Buenas prácticas

> [!TIP]
>
> Guarda el `order` de cada pago en tu base de datos **antes** de llamar a la API, para evitar duplicados si hay un timeout. Ver [Idempotencia y reintentos](https://docs.vitawallet.io/idempotency-retries.md).

> [!TIP]
>
> Valida al beneficiario con `POST /beneficiaries/validate_beneficiary` antes de pagar para reducir rechazos.

> [!TIP]
>
> Concilia con `GET /transactions` filtrando por tus `order`.

## Endpoints clave

> [card] [Crear payin](https://docs.vitawallet.io/api-reference/payins/overview.md)
>
> `POST /payment_orders`

> [card] [Métodos por país](https://docs.vitawallet.io/api-reference/direct-payment/overview.md)
>
> `GET /payment_methods/{country_iso_code}`

> [card] [Crear payout](https://docs.vitawallet.io/api-reference/bank-payouts/create-payout.md)
>
> `POST /transactions` con `transactions_type: "withdrawal"`

> [card] [Validar beneficiario](https://docs.vitawallet.io/api-reference/bank-payouts/overview.md)
>
> `POST /beneficiaries/validate_beneficiary`


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