Changelog - ON RAMP by Mesadepagos

Consulta los cambios incorporados en cada versión y accede a la documentación correspondiente para conocer contratos, ejemplos y formas de prueba.

Cambios posteriores a v2.3.0

Nuevos endpoints y cambios de contratos

Esta entrada reúne los cambios incorporados al repositorio desde la entrada del 23 de septiembre de 2026, incluida la actualización de documentación del 16 de octubre.

Nuevas rutas de API v3

Endpoint	Request	Response y comportamiento
`POST /v3/transactions/deposit/qr`	`fundingSource`, `referenceId` y `fiatCurrency: "BOB"` obligatorios. Con `balance` requiere `fiatAmount`; con `conversion`, `cryptoAmount` y `depositAddress`. `country` es `BO` por defecto; `qrExpirationTime` usa `HH:MM:SS` y tiene valor predeterminado `00:15:00`.	`201` con `transactionId`, `type`, `transactionStatus`, `requestedCryptoAmount`, `calculatedFiatAmount`, `exchangeRate`, `feeAmount` opcional, `asset`, `country`, `countryName`, `qrCodeBase64`, `referenceId` y `fiatCurrency`. Los montos de respuesta son texto. La confirmación del cobro se notifica por webhook.
`POST /v3/transactions/payouts/validate/qr`	`{image}` con imagen QR en base64; se eliminan espacios y saltos de línea antes de validar.	`201` con `numeroReferencia`, `monto`, `moneda`, `glosa`, `cuentaDestino`, `ciNitDestino`, `titularDestino`, `codigoBancoDestino`, `nombreBancoDestino` y `fechaVencimiento`.
`POST /v3/transactions/payouts/qr`	`fundingSource`, `externalReference` (1 a 32 caracteres) e `image` obligatorios; `assetDeposit`, `blockchain` y `amount` opcionales. Admite fondeo por `balance` o `conversion`.	`201` o `202` con `transactionId`, `externalReference`, `amount`, `currency`, `referenceNumber`, `amountDeposit`, `depositAddress` y `transactions`. Los montos son texto; `amountDeposit` y `depositAddress` pueden ser `null`. Con conversión devuelve los datos de fondeo y deja el pago pendiente.
`GET /v3/transactions/payouts/bank/banks`	Query `country` opcional, `BO` por defecto.	`200` con `{banks: [{code, name}]}`. Si falla el proveedor, responde `503` en lugar de una lista vacía.
`GET /v3/transactions/payouts/balance`	JWT del partner; sin parámetros adicionales.	`200` con un objeto `{fiat, available, accounting, held, lastCredit, lastDebit}` para la cuenta del negocio. Los saldos son números y las fechas pueden ser `null`. Responde `400` si no hay cuenta configurada y `503` si no se puede obtener el saldo. El listado de balances de v2 conserva su contrato.
`POST /v3/virtual-accounts`	Mismo contrato que v2: `country: "BO"` obligatorio; `currency`, `label` y `externalReference` opcionales.	Mismo contrato de creación que v2, disponible también en v3.
`GET /v3/virtual-accounts`	Filtros opcionales `currency` y `clientId`, iguales a v2.	`{virtualAccounts: [...]}`, con el mismo contrato de v2.
`GET /v3/virtual-accounts/{id}`	UUID de la cuenta del partner.	Cuenta virtual o `404`, con el mismo contrato de v2.

En payout QR v3, amount es obligatorio para un QR sin monto fijo. Si el QR ya tiene monto, el valor enviado debe coincidir. La descripción se obtiene del QR y, cuando está vacía, se asigna una descripción predeterminada.

Estados y errores de pagos v3

POST /v3/transactions/payouts/bank incorpora respuestas de error estructuradas en v3 y conserva su request y sus nombres de respuesta en snake_case. El payout QR v3 utiliza los nombres de campos indicados en la tabla anterior.Cuando un payout ACH o QR no tiene un resultado confirmado del proveedor, la API puede responder 202 Accepted con una transacción en processing_transaction. No reenvíes el pago ni cambies la referencia para intentar pagarlo otra vez: el proveedor pudo haberlo ejecutado. En ACH el resultado final se notifica por webhook. La generación de un QR de depósito no mueve fondos y no responde 202.Los errores de negocio de los pagos v3 usan {statusCode, code, message}: 404 TRANSACTION_NOT_FOUND, 409 TRANSACTION_REJECTED, 410 QR_EXPIRED, 422 INSUFFICIENT_FUNDS, 500 INTERNAL_SERVER_ERROR o 503 PAYMENT_PROVIDER_UNAVAILABLE, según la operación. Un dato del partner rechazado por el proveedor devuelve 400 con message: [{path, message}], indicando el campo del request. La consulta de balance v3 usa su propio contrato de error.

Cambios en endpoints existentes

Endpoint	Cambio
`GET /v2/transactions/balance/qr`	Se incorpora a la referencia pública. Ya existía: devuelve `{balance, fiatCurrency}`, con `balance` como texto, calculado con los depósitos QR creados en el día que estén completados. También sigue disponible en v1.
`POST /v2/transactions/payouts/validate/qr`	El campo `image` admite base64 con espacios o saltos de línea, que se eliminan antes de validar.
`POST /v2/transactions/payouts/qr`	La imagen se procesa como base64 puro, sin el prefijo `data:image/...;base64,`. Se mejora la lectura de imágenes QR grandes.
`POST /v1/transactions/payouts/bank` y `POST /v2/transactions/payouts/bank`	Si el saldo disponible no alcanza para enviar el pago, responde `500` con un mensaje de saldo insuficiente.
`POST /v1/transactions/payouts/bank/batch`	Verifica el saldo disponible por moneda y admite autorización parcial del lote. Los elementos sin fondos se devuelven como `FAILED`; los autorizados, como `PENDING`. Mantiene el orden del request. Si ninguno tiene fondos suficientes, devuelve `success: false` y `batch_id: null`.
`GET /v1/transactions/payouts/bank/status/{transactionId}`	Refleja los estados reales de las operaciones, incluidos los fallos por fondos insuficientes, mediante los estados públicos `COMPLETED`, `PENDING`, `CANCELLED` y `FAILED`.
`POST /v2/transactions/payouts/bank`	Corrección de documentación: `transaction.destination_holder` es obligatorio; `first_name`, `last_name`, `country`, `entity_type` y `document_type` son opcionales. Los nombres opcionales no reemplazan a `destination_holder` ni se usan para formar el titular. No cambia la validación ni el procesamiento de este endpoint.
`GET /v2/business-clients`	Se corrige `externalClientId` para devolver el identificador de la cuenta de pagos del cliente, o `null` si no existe.

Webhooks de clientes y transacciones

Endpoint	Cambio de contrato
`POST /v2/webhooks`	`events` admite los grupos `transaction` y `businessClient`; cada grupo omitido toma `[]`. Para cambios de estado de clientes, envía `events.businessClient: ["business_client_status_updated"]`.
`PATCH /v2/webhooks/{id}`	Permite actualizar cada grupo de eventos por separado. Omitir un grupo conserva sus suscripciones; enviar `[]` las elimina. Omitir `status` conserva el estado actual del webhook.
`GET /v2/webhooks` y `GET /v2/webhooks/{id}`	`events` devuelve los grupos separados `transaction` y `businessClient`.

El nuevo evento business_client_status_updated contiene id (UUID del cliente), type, occurredAt, businessId y data con name, type, country, previousStatus y status. Los estados públicos son PENDING, ONBOARDING, ACTIVE, REJECTED y SUSPENDED. El header x-webhook-event-id identifica la notificación para deduplicar entregas.Los webhooks de transacciones agregan details.description, siempre como texto ("" si no hay descripción). Los tipos deposit_express y deposit_virtual_account pueden incluir details.payer con name, documentNumber, accountNumber y bankCode, además de documentType y bankName cuando están disponibles. Las notificaciones se envían únicamente a webhooks activos suscritos al evento correspondiente. En las notificaciones de deposit_crypto se corrige el walletId asociado al depósito.

Ver referencia API v3

Revisa los contratos y las opciones de integración de v3.

Ver contratos de webhooks

Consulta las suscripciones, los payloads de transacciones y los logs de entrega.

v2.3.0

Cuentas virtuales y cobros nominados

Se incorpora el módulo de cuentas virtuales para cuentas BOB del partner y cuentas de cobro a nombre de sus clientes. Los cambios de contrato son los siguientes:

Endpoint	Cambio de request	Cambio de response
`POST /v2/virtual-accounts`	Nuevo. `country: "BO"` obligatorio; `currency: "BOB"`, `label` y `externalReference` opcionales.	`201` con cuenta virtual; `409` si el partner ya tiene una en ese país.
`GET /v2/virtual-accounts`	Nuevo. Filtros opcionales `currency` y `clientId`.	`{virtualAccounts: [...]}`. Sin filtros devuelve cuentas nominadas; `currency=BOB` devuelve la del partner.
`GET /v2/virtual-accounts/{id}`	Nuevo. UUID de cuenta del partner.	Cuenta virtual o `404`; las cuentas de clientes se consultan en el listado.
`POST /v2/business-clients`	Se agregan `settlementNetwork` (`Ethereum`/`Polygon`) y `settlementAsset` (`USDC`/`USDT`) opcionales.	Mantiene `{clientId, clientLink}`; responde `400` si la combinación de liquidación no está disponible.
`GET /v2/business-clients/{clientId}/endorsements`	Nuevo. UUID del cliente.	Arreglo de verificaciones, con estado y requisitos por sujeto.
`POST /v2/business-clients/{clientId}/endorsements`	Nuevo. `currencies` opcional (`EUR`, `USD`, `AED`, `AUD`, `GBP`); sin cuerpo solicita todas.	`{endorsements, failed}` para distinguir solicitudes aceptadas de monedas que requieren atención.
`POST /v2/business-clients/{clientId}/endorsements/subjects/{subjectId}/link`	Nuevo. UUID del cliente y del sujeto.	`{url, issuedAt, expiresAt}`; el enlace vence a los siete días.
`PUT /v2/business-clients/{clientId}/withdrawal-address`	Nuevo, solo Sandbox. `{address}` con formato EVM.	`{address, network, registeredAt}`; reemplaza la dirección anterior.
`GET /v2/business-clients/{clientId}/withdrawal-address`	Nuevo, solo Sandbox. UUID del cliente.	La dirección vigente o `null`.
`GET /v2/transactions/history`	El filtro `type` acepta `deposit_virtual_account`.	Las transacciones pueden incluir `type: "deposit_virtual_account"`; `amountFiat`/`fiatCode` pueden iniciar en `0`/`N/A`.

La respuesta unificada de cuentas virtuales contiene id, owner (business o businessClient), country, currency, paymentMethods, status, label, externalReference, coordinates y createdAt. coordinates y varios campos del titular pueden ser null; los datos bancarios dependen del riel.Los webhooks de transacciones pueden incluir el nuevo transactionType: "deposit_virtual_account". Su details.amount es texto y details.currency es la moneda fiat. La primera notificación puede informar "0" y "N/A" mientras se completa la información del proveedor.

Ver cuentas virtuales

Consulta el flujo, los contratos y los ejemplos completos.

Ver webhooks de cobro

Revisa el nuevo payload y su caso de datos pendientes.

v2.2.0

Cripto, payouts y prefunding

Esta versión mejora el registro y seguimiento de operaciones cripto, flexibiliza las referencias de Payout ACH v3 y automatiza el procesamiento de prefunding.

Registro automático de depósitos cripto

Los depósitos recibidos en las direcciones de una wallet ahora se registran automáticamente cuando son confirmados por la red blockchain. Cada depósito queda asociado al negocio y la wallet correspondientes, con información del monto, activo, blockchain y hash de la transacción.

Ver flujo de depósitos cripto

Consulta cómo recibir fondos y dar seguimiento a su confirmación.

Webhooks cripto con hash de transacción

Las notificaciones de depósitos y retiros cripto ahora pueden incluir transactionHash, además de amount, asset, blockchain y, cuando corresponde, walletId. El hash permite verificar la operación directamente en un explorador blockchain.

Ver contratos de Webhooks

Revisa los payloads actualizados de deposit_crypto y withdrawal_crypto.

Red predeterminada de nuevas wallets por ambiente

Las nuevas wallets incorporan USDC como activo predeterminado. La blockchain asignada depende del ambiente: Ethereum en Sandbox y Polygon en Producción. Este cambio no modifica los assets de wallets ya existentes.

Antes de transferir fondos, verifica siempre el valor de blockchain devuelto por la API y utiliza la misma red en la wallet de origen.

Respuesta controlada de balances de payout

La consulta de balances de Payout ACH y Payout QR ahora mantiene una respuesta válida cuando el proveedor de saldos no está disponible temporalmente. En ese escenario, la API devuelve los balances en cero hasta que la consulta pueda restablecerse.

Consultar balances de payout

Revisa la ruta y el contrato de respuesta de balances.

Referencias flexibles en Payout ACH v3

El campo obligatorio external_reference de Payout ACH v3 ahora acepta referencias de texto definidas por el partner y ya no exige el formato UUID v4. Esto permite utilizar identificadores propios de órdenes u operaciones.

Ver Payout ACH v3

Consulta el request, sus validaciones y la respuesta del payout.

Procesamiento automático de prefunding

Las operaciones de prefunding ahora continúan automáticamente con su procesamiento bancario después de confirmarse la recepción de fondos. El número de referencia generado por el proveedor queda asociado a la transacción para facilitar su trazabilidad.

v2.1.0

Wallets, cripto y PIX

Esta versión amplía la API v2 con nuevas operaciones de wallets, depósitos y payouts cripto, y pagos instantáneos PIX.

Administración de wallets

Se agregaron endpoints para crear y listar wallets, asociar assets por blockchain y consultar balances disponibles.

Ver documentación de Wallets

Revisa los endpoints, contratos y ejemplos de creación y consulta.

Depósitos cripto

Las direcciones asociadas a una wallet ahora pueden utilizarse para recibir depósitos cripto y consultar posteriormente su balance.

Ver flujo de depósitos cripto

Consulta cómo obtener una dirección, transferir fondos y validar el depósito.

Payouts cripto

Se agregó el envío de USDC y USDT desde una wallet interna hacia una dirección externa en Polygon, Ethereum o TRON.

Ver documentación de Payout Crypto

Revisa el request, response, validaciones y ejemplo Sandbox.

Payouts PIX

Se incorporaron pagos instantáneos en BRL hacia Brasil, con fondeo mediante balance o conversión cripto.

Ver documentación de Payout PIX

Consulta las claves PIX admitidas y las respuestas de cada modalidad de fondeo.

Webhooks cripto

Las notificaciones de depósitos y retiros cripto ahora incluyen amount, asset, blockchain y, cuando corresponde, walletId.

Ver contratos de Webhooks

Revisa los payloads de deposit_crypto y withdrawal_crypto.

Si tu integración ya procesa webhooks cripto, utiliza asset y blockchain en lugar de depender de currency.

​Nuevos endpoints y cambios de contratos

​Nuevas rutas de API v3

​Estados y errores de pagos v3

​Cambios en endpoints existentes

​Webhooks de clientes y transacciones

Ver referencia API v3

Ver contratos de webhooks

​Cuentas virtuales y cobros nominados

Ver cuentas virtuales

Ver webhooks de cobro

​Cripto, payouts y prefunding

​Registro automático de depósitos cripto

Ver flujo de depósitos cripto

​Webhooks cripto con hash de transacción

Ver contratos de Webhooks

​Red predeterminada de nuevas wallets por ambiente

​Respuesta controlada de balances de payout

Consultar balances de payout

​Referencias flexibles en Payout ACH v3

Ver Payout ACH v3

​Procesamiento automático de prefunding

​Wallets, cripto y PIX

​Administración de wallets

Ver documentación de Wallets

​Depósitos cripto

Ver flujo de depósitos cripto

​Payouts cripto

Ver documentación de Payout Crypto

​Payouts PIX

Ver documentación de Payout PIX

​Webhooks cripto

Ver contratos de Webhooks

Nuevos endpoints y cambios de contratos

Nuevas rutas de API v3

Estados y errores de pagos v3

Cambios en endpoints existentes

Webhooks de clientes y transacciones

Cuentas virtuales y cobros nominados

Cripto, payouts y prefunding

Registro automático de depósitos cripto

Webhooks cripto con hash de transacción

Red predeterminada de nuevas wallets por ambiente

Respuesta controlada de balances de payout

Referencias flexibles en Payout ACH v3

Procesamiento automático de prefunding

Wallets, cripto y PIX

Administración de wallets

Depósitos cripto

Payouts cripto

Payouts PIX

Webhooks cripto