Integración por API

Envía pagos desde tu cuenta de Volet.com a usuarios de Volet.com y a billeteras cripto externas mediante la Merchant API.

La Mass Payout API permite que tu aplicación cree, valide y siga transacciones de pago de forma programática.

Puedes usar la API en tres escenarios principales:

Pagos a usuarios de Volet.com: envía fondos desde tu cuenta de Volet.com a otra cuenta de Volet.com.
Pagos cripto sin conversión: envía criptomonedas desde el mismo saldo cripto a una billetera cripto externa.
Pagos cripto con conversión: envía criptomonedas a una billetera cripto externa desde otro saldo compatible, como USD, EUR, USDT u otra criptomoneda.

Cómo funcionan los pagos masivos mediante la API

La Merchant API crea una transacción de pago por solicitud.

Para los lotes de pagos masivos, tu backend prepara una lista de destinatarios y crea una transacción de pago separada para cada elemento del lote.

Un flujo típico por lotes:

Prepara un lote de pagos en tu sistema.
Consulta los saldos disponibles en tus billeteras de Volet.com.
Consulta los límites, las tarifas y los tipos de cambio cuando sea necesario.
Valida cada pago antes de crearlo.
Crea las transacciones de pago mediante la API.
Guarda en tu sistema los ID de transacción devueltos.
Sigue el estado de los pagos mediante la API.
Concilia los pagos completados, fallidos, cancelados o reembolsados.

Antes de empezar

Para enviar pagos masivos mediante la API, necesitas:

Una cuenta de Volet.com verificada.
Una API configurada en la sección Herramientas de pago.
Saldo suficiente en tu cuenta de Volet.com.
Los datos de los destinatarios que exige cada método de pago.

Consulta Activar los pagos masivos para crear y configurar tu API.

Autenticación

Las solicitudes a la Merchant API requieren encabezados de autenticación.

Incluye los siguientes encabezados en cada solicitud a la API:

Encabezado	Descripción
`Api-Name`	Nombre de la API configurado en tu cuenta de Volet.com.
`Account-Email`	Email de la cuenta de Volet.com a la que pertenece la API.
`Authentication-Token`	Token de autenticación de la solicitud, generado con el secreto de tu API.

Mantén en privado el secreto de tu API. Nunca expongas las credenciales de la API ni los tokens de autenticación en código frontend, apps móviles, bots o scripts del lado del cliente.

Flujo de pago recomendado

Antes de crear los pagos, tu backend debe validar y preparar cada elemento.

Flujo recomendado:

Consulta los saldos de las billeteras.
Consulta los límites mínimos del método de pago y la moneda elegidos.
Consulta las tarifas o comisiones.
Consulta el tipo de cambio si el pago usa conversión.
Valida la solicitud de pago.
Crea la transacción de pago.
Guarda el transactionId devuelto.
Consulta periódicamente el estado de la transacción hasta que el pago alcance un estado final.

Paso 1: consultar los saldos de las billeteras

Usa este método para consultar los saldos disponibles en tus billeteras de Volet.com antes de crear los pagos.

Endpoint:

GET /api/account/balances

Ejemplo de respuesta:

[
  {
    "walletId": "W000000000001",
    "amount": 1000.50,
    "currency": "USD"
  },
  {
    "walletId": "W000000000002",
    "amount": 2500,
    "currency": "USDT"
  }
]

Usa walletId como billetera de origen al crear las solicitudes de pago.

Paso 2: consultar límites y tarifas

Antes de enviar pagos, consulta los límites mínimos y las tarifas del método de pago y del par de monedas elegidos.

Límites mínimos:

GET /api/account/limits/min

Tarifas:

GET /api/account/tariffs

Usa estos métodos para evitar errores al crear pagos por montos, monedas o métodos de pago no admitidos.

Paso 3: consultar el tipo de cambio

Consulta el tipo de cambio cuando el pago requiere conversión.

Endpoint:

POST /api/exchange-rate/information

Úsalo antes de crear pagos en los que la moneda de origen y la moneda del pago son distintas.

Casos de uso de ejemplo:

Enviar USDT a una billetera cripto externa desde un saldo en USD.
Enviar BTC a una billetera cripto externa desde un saldo en EUR.
Convertir un saldo cripto compatible en otra moneda de pago.

Método 1: enviar pagos a usuarios de Volet.com

Usa este método cuando el destinatario tiene una cuenta de Volet.com.

Los fondos se transfieren internamente de tu cuenta de Volet.com a la cuenta de Volet.com del destinatario.

Este método no requiere confirmación en la blockchain ni usa direcciones de billeteras cripto externas.

Validar un pago a un usuario de Volet.com

Valida el pago antes de crear la transacción.

Endpoint:

POST /api/withdrawal/validation/internal-other

Ejemplo de solicitud:

{
  "srcWalletId": "W000000000001",
  "amount": 25,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 001",
  "srcCurrency": "USD",
  "destCurrency": "USD",
  "destEmail": "[email protected]"
}

La validación verifica los datos del pago sin crear una transacción.

Crear un pago a un usuario de Volet.com

Tras una validación exitosa, crea la transacción de pago.

Endpoint:

POST /api/withdrawal/internal-other

Ejemplo de solicitud:

{
  "srcWalletId": "W000000000001",
  "amount": 25,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 001",
  "srcCurrency": "USD",
  "destCurrency": "USD",
  "destEmail": "[email protected]"
}

Ejemplo de respuesta:

{
  "transactionId": "11111111-1111-4111-8111-111111111111",
  "paymentMethodType": "INTERNAL_OTHER",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USD",
  "amount": 25,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000001",
  "fullCommission": 0.13,
  "comment": "Payout batch 2026-06-26 / recipient 001"
}

Guarda el transactionId devuelto en tu sistema y úsalo para seguir el estado del pago.

Opcional: validar las cuentas de Volet.com de los destinatarios

Si tu flujo recopila los emails de los destinatarios antes de crear los pagos, puedes comprobar si existen las cuentas de Volet.com antes de crear las solicitudes.

Endpoint:

GET /api/account/exists

También puedes verificar los datos del titular de la cuenta si tu flujo requiere controles adicionales del destinatario.

Endpoint:

GET /api/account/matching

Usa estos métodos para reducir los pagos fallidos por datos incorrectos del destinatario.

Método 2: enviar pagos cripto sin conversión

Usa este método cuando quieres enviar criptomonedas desde el mismo saldo cripto a una billetera cripto externa.

Por ejemplo:

Enviar USDT desde tu saldo en USDT a una dirección USDT TRC-20 externa.
Enviar BTC desde tu saldo en BTC a una dirección BTC externa.
Enviar ETH desde tu saldo en ETH a una dirección ETH externa.

El destinatario no necesita una cuenta de Volet.com.

Validar un pago cripto sin conversión

Valida el pago cripto antes de crear la transacción.

Endpoint:

POST /api/withdrawal/validation/cryptowallet

Ejemplo de solicitud:

{
  "srcWalletId": "W000000000002",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 002",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "email": "[email protected]"
  }
}

Usa el destCurrency correcto para el token y la red blockchain del pago.

En las redes que exigen memo, etiqueta de destino u otro identificador similar, inclúyelo en el campo address.memo.

Ejemplo:

{
  "address": {
    "address": "rXXXXXXXXXXXXXXXXXXXXXXXX",
    "memo": "123456"
  }
}

Crear un pago cripto sin conversión

Tras una validación exitosa, crea la transacción de pago.

Endpoint:

POST /api/withdrawal/cryptowallet

Ejemplo de solicitud:

{
  "srcWalletId": "W000000000002",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 002",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "email": "[email protected]"
  }
}

Ejemplo de respuesta:

{
  "transactionId": "22222222-2222-4222-8222-222222222222",
  "paymentMethodType": "CRYPTO_WALLET",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USDT",
  "amount": 100,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000002",
  "fullCommission": 0.25,
  "comment": "Payout batch 2026-06-26 / recipient 002"
}

Método 3: enviar pagos cripto con conversión

Usa este método cuando el saldo de origen y la moneda del pago son distintos.

Por ejemplo:

Enviar USDT a una billetera externa desde un saldo en USD.
Enviar BTC a una billetera externa desde un saldo en EUR.
Enviar USDC por una red compatible desde otro saldo compatible.

El destinatario recibe criptomonedas en una billetera cripto externa. La conversión se realiza durante el flujo de pago.

Validar un pago cripto con conversión

Valida el pago antes de crear la transacción.

Endpoint:

POST /api/withdrawal/validation/crypto-external

Ejemplo de solicitud:

{
  "srcWalletId": "W000000000001",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 003",
  "srcCurrency": "USD",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "firstName": "Alex",
    "lastName": "Example",
    "email": "[email protected]"
  }
}

Usa srcCurrency para definir la moneda del saldo de origen y destCurrency para definir la criptomoneda y la red que se envían al destinatario.

Crear un pago cripto con conversión

Tras una validación exitosa, crea la transacción de pago.

Endpoint:

POST /api/withdrawal/crypto-external

Ejemplo de solicitud:

{
  "srcWalletId": "W000000000001",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 003",
  "srcCurrency": "USD",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "firstName": "Alex",
    "lastName": "Example",
    "email": "[email protected]"
  }
}

Ejemplo de respuesta:

{
  "transactionId": "33333333-3333-4333-8333-333333333333",
  "paymentMethodType": "CRYPTO_EXTERNAL",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USD",
  "amount": 100,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000001",
  "fullCommission": 0.50,
  "comment": "Payout batch 2026-06-26 / recipient 003"
}

Campos de la solicitud

Campos comunes de las solicitudes de pago:

Campo	Obligatorio	Se usa en	Descripción
`srcWalletId`	No	Todos los métodos	ID de la billetera de origen en tu cuenta de Volet.com.
`amount`	Sí	Todos los métodos	Monto del pago. Cómo se interpreta depende de `action`.
`action`	Sí	Todos los métodos	Modo del monto. Valores posibles: `GIVE`, `GET`.
`note`	No	Todos los métodos	Nota interna o descripción del pago.
`srcCurrency`	No	Pagos a usuarios de Volet.com, pagos cripto con conversión	Moneda de origen del pago.
`destCurrency`	Sí	Todos los métodos	Moneda que se acredita al destinatario o se envía a la billetera cripto externa.
`destEmail`	No	Pagos a usuarios de Volet.com	Email de la cuenta de Volet.com del destinatario.
`destWalletId`	No	Pagos a usuarios de Volet.com	ID de la billetera del destinatario, cuando corresponda.
`address.address`	Sí	Pagos cripto externos	Dirección de la billetera cripto del destinatario.
`address.memo`	No	Pagos cripto externos	Memo, etiqueta de destino u otro identificador similar, si la red elegida lo exige.
`receiverInfo`	No	Pagos cripto externos	Información del destinatario, como nombre, email, fecha de nacimiento o razón social, cuando se requiera.

`GIVE` y `GET`

Usa action para definir cómo se interpreta el monto del pago.

Acción	Significado
`GIVE`	El monto se considera el monto a enviar desde el origen.
`GET`	El monto se considera el monto que debe recibir el destinatario, cuando se admite.

En los pagos con conversión de moneda, consulta el tipo de cambio antes de crear el pago. Así tu sistema puede mostrar o guardar los montos de origen y destino previstos antes de crear la transacción.

Seguimiento del estado de los pagos

Después de crear un pago, guarda el transactionId devuelto.

Usa la consulta de transacciones para obtener el estado más reciente del pago.

Endpoint:

GET /api/transactions/{id}

También puedes buscar en el historial de transacciones.

Endpoint:

GET /api/transactions

Filtros útiles:

Filtro	Descripción
`paymentDirections`	Filtrar por `DEPOSIT` o `WITHDRAWAL`.
`transactionStatus`	Filtrar por estado de la transacción.
`wallets`	Filtrar por ID de billetera.
`startDate` / `endDate`	Filtrar por rango de fechas de creación.
`searchLabel`	Buscar por etiqueta de texto, cuando corresponda.
`offset` / `limit`	Paginar los resultados.
`sortOrder`	Ordenar los resultados por fecha de creación.

Estados de las transacciones

Usa el estado de la transacción para actualizar el estado del pago en tu propio sistema.

Estado	Significado	Acción recomendada
`CREATED`	Se creó la transacción de pago.	Guarda la transacción y sigue consultando.
`READY_TO_PROCESS`	El pago está listo para procesarse.	Sigue consultando.
`PENDING`	El pago está pendiente.	Sigue consultando.
`PROCESSING`	El pago se está procesando.	Sigue consultando.
`EXCHANGING`	La conversión de moneda está en curso.	Sigue consultando.
`COMPLETED`	El pago se completó.	Marca el pago como completado en tu sistema.
`CANCELLING`	La cancelación está en curso.	Espera el estado final.
`CANCELED`	El pago se canceló.	Marca el pago como cancelado.
`REFUNDING`	El reembolso está en curso.	Espera el estado final.
`REFUNDED`	El pago se reembolsó.	Marca el pago como reembolsado.

Considera el pago como completado solo cuando el estado pase a COMPLETED.

Cancelar pagos

Algunas transacciones se pueden cancelar mientras la cancelación siga siendo posible.

Endpoint:

DELETE /api/transactions/{transactionId}

La posibilidad de cancelar depende del método de pago, el estado de la transacción y la etapa de procesamiento.

No cuentes con la cancelación de los pagos cripto una vez difundida la transacción en la blockchain. Confirma todas las direcciones, monedas, redes y montos de los destinatarios antes de crear el pago.

Recomendaciones para el procesamiento por lotes

En los pagos masivos, tu backend debe gestionar el ciclo de vida del lote.

Enfoque recomendado:

Asigna un ID interno al lote de pagos.
Asigna un ID interno a cada pago.
Valida cada elemento antes de crear las transacciones.
Crea transacciones solo para los elementos validados.
Guarda la relación entre tu ID interno de elemento y el transactionId devuelto.
Sigue cada transacción por separado.
Reintenta solo los elementos fallidos o no creados.
Concilia los estados finales antes de marcar el lote como completado.

Evita enviar pagos duplicados. Si tu aplicación reintenta una solicitud tras un tiempo de espera agotado, comprueba primero si ya se creó una transacción para ese elemento.

Gestión de errores

Los errores de la Merchant API devuelven respuestas de error estructuradas.

Casos de error habituales:

Estado HTTP	Significado
`400`	La solicitud tiene un formato incorrecto o contiene parámetros no válidos.
`401`	Faltan los encabezados de autenticación o no son válidos.
`403`	La API no tiene permiso para usar la operación solicitada.
`404`	No se encontró el recurso solicitado.
`500`	Error inesperado del servidor.

Cuando se produce un error:

Registra errorId para soporte y diagnóstico.
Revisa errorField para identificar el campo de la solicitud relacionado con el error.
No crees automáticamente un pago de reemplazo hasta confirmar que no se creó ninguna transacción.
Reintenta solo cuando sea seguro hacerlo.

Lista de verificación de pruebas

Antes de enviar pagos masivos reales, prueba el flujo completo.

Para pagos a usuarios de Volet.com:

Validación de la cuenta del destinatario.
Validación del pago.
Creación del pago.
Seguimiento del estado de la transacción.
Escenarios completados, cancelados y fallidos.

Para pagos cripto sin conversión:

Elección correcta del token y la red.
Gestión de la dirección y el memo.
Validación del pago.
Creación del pago.
Seguimiento de la transacción en la blockchain.
Gestión de direcciones incorrectas o redes no compatibles.

Para pagos cripto con conversión:

Consulta de saldo.
Consulta del tipo de cambio.
Validación del pago.
Creación del pago.
Estados EXCHANGING y COMPLETED.
Conciliación de montos entre la moneda de origen y la de destino.

Para el procesamiento por lotes:

Gestión de fallos parciales del lote.
Lógica de reintentos.
Prevención de duplicados.
Relación interna entre lotes y transacciones.
Informe final de conciliación.

Notas importantes

La API crea una transacción de pago por solicitud.
Tu backend es responsable de orquestar los lotes.
Valida siempre los pagos antes de crear las transacciones.
Guarda siempre los valores de transactionId devueltos.
Usa la consulta de transacciones o el historial para seguir el estado final.
No marques un pago como completado hasta que el estado sea COMPLETED.
En los pagos cripto, verifica siempre la dirección, el token, la red y el memo del destinatario antes de crear la transacción.
Enviar cripto a una dirección o red incorrecta puede provocar la pérdida permanente de los fondos.
Nunca expongas las credenciales de la API en el código frontend.

Activar los pagos masivos — configura tu API antes de enviar pagos
Enviar pagos a usuarios de Volet.com — envía pagos internos a cuentas de Volet.com
Enviar pagos cripto custodiales — envía cripto a billeteras externas desde tu cuenta de Volet.com
Descripción general de los pagos masivos — compara los métodos y modelos de pago
Referencia de la API — documentación completa de métodos, parámetros y respuestas

Cómo funcionan los pagos masivos mediante la API​

Antes de empezar​

Autenticación​

Flujo de pago recomendado​

Paso 1: consultar los saldos de las billeteras​

Paso 2: consultar límites y tarifas​

Paso 3: consultar el tipo de cambio​

Método 1: enviar pagos a usuarios de Volet.com​

Validar un pago a un usuario de Volet.com​

Crear un pago a un usuario de Volet.com​

Opcional: validar las cuentas de Volet.com de los destinatarios​

Método 2: enviar pagos cripto sin conversión​

Validar un pago cripto sin conversión​

Crear un pago cripto sin conversión​

Método 3: enviar pagos cripto con conversión​

Validar un pago cripto con conversión​

Crear un pago cripto con conversión​

Campos de la solicitud​

GIVE y GET​

Seguimiento del estado de los pagos​

Estados de las transacciones​

Cancelar pagos​

Recomendaciones para el procesamiento por lotes​

Gestión de errores​

Lista de verificación de pruebas​

Notas importantes​

Relacionado​

Cómo funcionan los pagos masivos mediante la API

Antes de empezar

Autenticación

Flujo de pago recomendado

Paso 1: consultar los saldos de las billeteras

Paso 2: consultar límites y tarifas

Paso 3: consultar el tipo de cambio

Método 1: enviar pagos a usuarios de Volet.com

Validar un pago a un usuario de Volet.com

Crear un pago a un usuario de Volet.com

Opcional: validar las cuentas de Volet.com de los destinatarios

Método 2: enviar pagos cripto sin conversión

Validar un pago cripto sin conversión

Crear un pago cripto sin conversión

Método 3: enviar pagos cripto con conversión

Validar un pago cripto con conversión

Crear un pago cripto con conversión

Campos de la solicitud

`GIVE` y `GET`

Seguimiento del estado de los pagos

Estados de las transacciones

Cancelar pagos

Recomendaciones para el procesamiento por lotes

Gestión de errores

Lista de verificación de pruebas

Notas importantes

Relacionado