Cómo funciona

La API tiene cuatro objetos. El resto son consultas (saldo, consumo, catálogo de bancos) o bloques que viajan dentro de una petición (el remitente).

  Cotización ──────┐                POST /v1/quotes        → quote.id
  (quote)          │  1 uso, ~60 s  POST /v1/beneficiaries → beneficiary.id
                   ▼                POST /v1/payouts       → payment.id
  Beneficiario ─► Dispersión ─► Evento ─► tu webhookUrl    (consume la quote)
  (beneficiary)    (payment)     (event)      ⋮ asíncrono
                       │                 POST tu webhookUrl ← event
                       └─► historia (payment.events[])

El evento es payment.settled, payment.failed o payment.reversed. El beneficiario es opcional: puede ir en línea en POST /v1/payouts.

Cotización

Fija cuánto se entrega, cuánto cobramos y cuánto se te debita. POST /payouts no acepta ningún monto. Mandas amount en deliver (lo que recibe el beneficiario) o en spend (lo que se te cobra), nunca en los dos; la respuesta es la misma en ambos casos, y GET /quotes/{id} la devuelve idéntica.

Un solo uso. Consumirla dos veces devuelve 409 quote_already_consumed.
Caduca. TTL ~60 s. Pasada expires_at, 422 quote_expired.
Cotizar es gratis: no reserva saldo, no consume límites y no genera consumo facturable.

Campo	Tipo	Qué es
`id`	uuid	Lo que mandas en `quoteId` al dispersar
`fixed`	`deliver` · `spend`	Qué lado fijaste tú
`spend`	`{ asset, amount }`	Lo que se te cobra
`deliver`	`{ asset, amount }`	Lo que cobra el beneficiario
`fee`	`{ asset, amount }`	Nuestra comisión, siempre en el activo entregado
`rate`	objeto · null	`{ value, market, spread_bps }`, o `null` si no hay conversión
`status`	`open` · `consumed` · `expired`
`expires_at` · `created_at`	ISO-8601	Pasada `expires_at` no sirve

Fijando deliver, la comisión se suma encima; fijando spend, lo que llega sale de la tasa menos comisión. Ver cotizar en bolívares.

Beneficiario

A quién se le paga. El alta es idempotente por (cédula, banco, instrumento): reenviar los mismos datos devuelve el mismo beneficiario con created: false.

Campo	Tipo	Qué es
`id`	uuid	Lo que mandas en `beneficiaryId` al dispersar
`full_name`	string	Nombre tal como lo tiene el banco destino
`national_id`	string	Cédula o RIF: `V/E/J/G/P` + 6 a 9 dígitos
`bank_code`	string	Banco destino, 4 dígitos (`0102`, `0134`, `0138`…)
`account_number`	string · null	Cuenta de 20 dígitos que empieza por `bank_code`. Necesaria para `transferencia`
`phone`	string · null	Móvil `04XXXXXXXXX`. Necesario para los dos instrumentos
`asset` · `country`	string	`BS` · `VE`
`status`	`active` · `blocked`	Un beneficiario bloqueado da `422 beneficiary_blocked`
`payout_count`	int	Dispersiones que le han llegado bien
`last_success_at` · `last_failure_reason`	ISO-8601 · string	Su historial
`created_at`	ISO-8601

Dispersión

Un payment. Consume una cotización y entrega el importe al beneficiario.

Campo	Tipo	Qué es
`id`	uuid
`status`	ver estados	`submitted` es el desenlace normal
`status_reason`	string · null	Por qué está donde está
`beneficiary_id`	uuid · null	A quién
`customer_id`	uuid · null	A qué usuario tuyo corresponde, si lo mandaste
`payout_asset` · `payout_amount`	`BS` · string	Lo que recibe el beneficiario
`source_asset` · `source_amount`	string	Lo que se te debitó: importe más comisión
`fee_amount`	string	Nuestra comisión. `0` en un pago `failed`: el asiento se revirtió entero
`method`	`pago_movil` · `transferencia`	Instrumento por el que salió
`bank_reference`	string · null	El comprobante que ve el beneficiario en su banco. Existe cuando el envío se completa; es el único identificador del envío que publicamos
`compensated`	bool	Si el asiento contable se revirtió
`settled_at`	ISO-8601 · null	Cuándo salió el dinero
`created_at`	ISO-8601	Cuándo lo pediste
`events[]`	array	Historia de transiciones (sólo en `GET /payments/{id}`)

Cada elemento de events[]:

Campo	Qué es
`from_status` · `to_status`	La transición
`reason`	`ledger_committed`, `rail_accepted`, `rail_accepted_async`, `resolved_by_reaper`, `rail_failed`, `rail_returned`, `provider_reported_failure`…
`actor`	`api` (tu llamada) · `provider_event` (nos avisó el riel) · `reaper` (nuestro proceso de resolución) · `system`
`metadata`	Contexto de la transición. En una dispersión, `methodRequested` y `methodUsed`
`created_at`	Cuándo

Evento

Cada webhook deja un event consultable, con el detalle de cada intento.

Campo	Tipo	Qué es
`id`	string	Deduplica por esto. También viaja en `x-event-id`
`event_type`	string	`payment.settled` · `payment.failed` · `payment.reversed`
`aggregate_type` · `aggregate_id`	string	Sobre qué objeto es (`payment` + su id)
`payload`	object	El cuerpo que enviamos (sólo en `GET /events/{id}`)
`status`	`pending` · `published` · `dead`	`dead` = tu cola de fallidos
`attempts`	int	Intentos consumidos
`last_error`	string · null	Por qué falló el último
`next_attempt_at` · `published_at` · `dead_at`	ISO-8601 · null
`deliveries[]`	array	Cada intento con su código HTTP y su latencia

Ver webhooks.

Bloques que no son objetos

sender (quién ordena el envío) viaja dentro de POST /payouts: no es un recurso y no tiene id. Ver dispersar. Tu posición (GET /treasury/position) y tu consumo (GET /limits/usage) son cifras vivas: no tienen id ni historia consultable.