Changelog - ON RAMP by Mesadepagos

Review the changes in each release and open the related documentation for contracts, examples, and testing instructions.

Changes since v2.3.0

New endpoints and contract changes

This entry covers changes incorporated into the repository since the September 23, 2026 entry, including the October 16 documentation update.

New API v3 routes

Endpoint	Request	Response and behavior
`POST /v3/transactions/deposit/qr`	Requires `fundingSource`, `referenceId`, and `fiatCurrency: "BOB"`. `balance` requires `fiatAmount`; `conversion` requires `cryptoAmount` and `depositAddress`. `country` defaults to `BO`; `qrExpirationTime` uses `HH:MM:SS` and defaults to `00:15:00`.	`201` with `transactionId`, `type`, `transactionStatus`, `requestedCryptoAmount`, `calculatedFiatAmount`, `exchangeRate`, optional `feeAmount`, `asset`, `country`, `countryName`, `qrCodeBase64`, `referenceId`, and `fiatCurrency`. Response amounts are strings. Payment confirmation is sent by webhook.
`POST /v3/transactions/payouts/validate/qr`	`{image}` containing a base64 QR image; whitespace and line breaks are removed before validation.	`201` with `numeroReferencia`, `monto`, `moneda`, `glosa`, `cuentaDestino`, `ciNitDestino`, `titularDestino`, `codigoBancoDestino`, `nombreBancoDestino`, and `fechaVencimiento`.
`POST /v3/transactions/payouts/qr`	Requires `fundingSource`, `externalReference` (1 to 32 characters), and `image`; `assetDeposit`, `blockchain`, and `amount` are optional. Supports `balance` and `conversion` funding.	`201` or `202` with `transactionId`, `externalReference`, `amount`, `currency`, `referenceNumber`, `amountDeposit`, `depositAddress`, and `transactions`. Amounts are strings; `amountDeposit` and `depositAddress` may be `null`. Conversion returns funding details and leaves the payout pending.
`GET /v3/transactions/payouts/bank/banks`	Optional `country` query, defaulting to `BO`.	`200` with `{banks: [{code, name}]}`. Provider failures return `503` instead of an empty list.
`GET /v3/transactions/payouts/balance`	Partner JWT; no additional parameters.	`200` with a single `{fiat, available, accounting, held, lastCredit, lastDebit}` object for the business account. Balances are numbers; dates may be `null`. Returns `400` when no account is configured and `503` when the balance cannot be retrieved. The v2 balance list retains its contract.
`POST /v3/virtual-accounts`	Same contract as v2: required `country: "BO"`; optional `currency`, `label`, and `externalReference`.	Same creation contract as v2, also available in v3.
`GET /v3/virtual-accounts`	Optional `currency` and `clientId` filters, as in v2.	`{virtualAccounts: [...]}`, using the v2 contract.
`GET /v3/virtual-accounts/{id}`	Partner account UUID.	Virtual account or `404`, using the v2 contract.

For QR payout v3, amount is required for a QR without a fixed amount. If the QR already specifies an amount, any supplied value must match it. The description comes from the QR; an empty description is replaced with a default.

Payment statuses and errors in v3

POST /v3/transactions/payouts/bank adds structured error responses in v3 and retains its request and snake_case response names. QR payout v3 uses the field names listed in the table above.When an ACH or QR payout has no confirmed provider result, the API may return 202 Accepted with a transaction in processing_transaction. Do not resend the payment or change its reference to try paying again: the provider may already have executed it. ACH final results are sent by webhook. Generating a deposit QR does not move funds and does not return 202.Business errors in v3 payment flows use {statusCode, code, message}: 404 TRANSACTION_NOT_FOUND, 409 TRANSACTION_REJECTED, 410 QR_EXPIRED, 422 INSUFFICIENT_FUNDS, 500 INTERNAL_SERVER_ERROR, or 503 PAYMENT_PROVIDER_UNAVAILABLE, depending on the operation. Partner data rejected by the provider returns 400 with message: [{path, message}], pointing to the request field. The v3 balance query uses its own error contract.

Changes to existing endpoints

Endpoint	Change
`GET /v2/transactions/balance/qr`	Added to the public reference. This route already existed: returns `{balance, fiatCurrency}`, with `balance` as a string, calculated from completed QR deposits created during the current day. It also remains available in v1.
`POST /v2/transactions/payouts/validate/qr`	The `image` field accepts base64 with whitespace or line breaks, which are removed before validation.
`POST /v2/transactions/payouts/qr`	Images are processed as plain base64, without the `data:image/...;base64,` prefix. Decoding of large QR images is improved.
`POST /v1/transactions/payouts/bank` and `POST /v2/transactions/payouts/bank`	If the available balance is insufficient to submit the payment, returns `500` with an insufficient-balance message.
`POST /v1/transactions/payouts/bank/batch`	Checks available balance per currency and supports partial batch authorization. Items without funds are returned as `FAILED`; authorized items return `PENDING`. Request order is preserved. If no item has sufficient funds, returns `success: false` and `batch_id: null`.
`GET /v1/transactions/payouts/bank/status/{transactionId}`	Reflects actual operation statuses, including insufficient-funds failures, through public statuses `COMPLETED`, `PENDING`, `CANCELLED`, and `FAILED`.
`POST /v2/transactions/payouts/bank`	Documentation correction: `transaction.destination_holder` is required; `first_name`, `last_name`, `country`, `entity_type`, and `document_type` are optional. Optional names neither replace `destination_holder` nor build the holder name. Endpoint validation and processing are unchanged.
`GET /v2/business-clients`	Corrects `externalClientId` to return the client’s payment account identifier, or `null` if none exists.

Client and transaction webhooks

Endpoint	Contract change
`POST /v2/webhooks`	`events` supports `transaction` and `businessClient` groups; each omitted group defaults to `[]`. To receive client status changes, send `events.businessClient: ["business_client_status_updated"]`.
`PATCH /v2/webhooks/{id}`	Event groups can be updated separately. Omitting a group preserves its subscriptions; sending `[]` removes them. Omitting `status` preserves the current webhook status.
`GET /v2/webhooks` and `GET /v2/webhooks/{id}`	`events` returns separate `transaction` and `businessClient` groups.

The new business_client_status_updated event contains id (client UUID), type, occurredAt, businessId, and data with name, type, country, previousStatus, and status. Public statuses are PENDING, ONBOARDING, ACTIVE, REJECTED, and SUSPENDED. The x-webhook-event-id header identifies the notification for delivery deduplication.Transaction webhooks add details.description, always a string ("" when no description exists). deposit_express and deposit_virtual_account may include details.payer with name, documentNumber, accountNumber, and bankCode, plus documentType and bankName when available. Notifications are sent only to active webhooks subscribed to the corresponding event. For deposit_crypto notifications, the walletId associated with the deposit is corrected.

View API v3 reference

Review v3 contracts and integration options.

View webhook contracts

Review subscriptions, transaction payloads, and delivery logs.

v2.3.0

Virtual accounts and named collections

The new virtual accounts module covers partner BOB accounts and collection accounts in clients’ names. Contract changes are listed below:

Endpoint	Request change	Response change
`POST /v2/virtual-accounts`	New. Required `country: "BO"`; optional `currency: "BOB"`, `label`, and `externalReference`.	`201` with a virtual account; `409` if the partner already has one in that country.
`GET /v2/virtual-accounts`	New. Optional `currency` and `clientId` filters.	`{virtualAccounts: [...]}`. Without filters, returns named client accounts; `currency=BOB` returns the partner account.
`GET /v2/virtual-accounts/{id}`	New. Partner account UUID.	Virtual account or `404`; use the list for client accounts.
`POST /v2/business-clients`	Adds optional `settlementNetwork` (`Ethereum`/`Polygon`) and `settlementAsset` (`USDC`/`USDT`).	Keeps `{clientId, clientLink}`; returns `400` if the settlement combination is unavailable.
`GET /v2/business-clients/{clientId}/endorsements`	New. Client UUID.	Array of endorsements with status and per-subject requirements.
`POST /v2/business-clients/{clientId}/endorsements`	New. Optional `currencies` (`EUR`, `USD`, `AED`, `AUD`, `GBP`); omitting the body requests all.	`{endorsements, failed}` separates accepted requests from currencies needing attention.
`POST /v2/business-clients/{clientId}/endorsements/subjects/{subjectId}/link`	New. Client and subject UUIDs.	`{url, issuedAt, expiresAt}`; the link expires after seven days.
`PUT /v2/business-clients/{clientId}/withdrawal-address`	New, Sandbox only. EVM formatted `{address}`.	`{address, network, registeredAt}`; replaces the previous address.
`GET /v2/business-clients/{clientId}/withdrawal-address`	New, Sandbox only. Client UUID.	Current address or `null`.
`GET /v2/transactions/history`	The `type` filter accepts `deposit_virtual_account`.	Transactions may include `type: "deposit_virtual_account"`; `amountFiat`/`fiatCode` may initially be `0`/`N/A`.

The unified virtual account response has id, owner (business or businessClient), country, currency, paymentMethods, status, label, externalReference, coordinates, and createdAt. coordinates and some holder fields may be null; bank details depend on the rail.Transaction webhooks may include the new transactionType: "deposit_virtual_account". Its details.amount is a string and details.currency is the fiat currency. The first notification may contain "0" and "N/A" while provider details are being completed.

View virtual accounts

Review the full flow, contracts, and examples.

View collection webhooks

Review the new payload and its pending-data case.

v2.2.0

Crypto, payouts, and prefunding

This release improves crypto operation tracking, makes Payout ACH v3 references more flexible, and automates prefunding processing.

Automatic crypto deposit registration

Deposits received at a wallet address are now registered automatically after blockchain confirmation. Each deposit is linked to the corresponding business and wallet, including its amount, asset, blockchain, and transaction hash.

View the crypto deposit flow

Learn how to receive funds and track their confirmation.

Crypto webhooks with transaction hashes

Crypto deposit and withdrawal notifications may now include transactionHash, in addition to amount, asset, blockchain, and, when applicable, walletId. Use the hash to verify the operation in a blockchain explorer.

View webhook contracts

Review the updated deposit_crypto and withdrawal_crypto payloads.

Default network for new wallets by environment

New wallets include USDC as their default asset. The assigned blockchain depends on the environment: Ethereum in Sandbox and Polygon in Production. Existing wallet assets are not changed.

Before transferring funds, always check the blockchain returned by the API and use the same network in the source wallet.

Controlled payout balance response

Payout ACH and Payout QR balance queries now preserve a valid response when the balance provider is temporarily unavailable. In this case, the API returns zero balances until service is restored.

Retrieve payout balances

Review the balance endpoint and its response contract.

Flexible references in Payout ACH v3

The required Payout ACH v3 external_reference field now accepts partner-defined text references and no longer requires UUID v4 format. This lets partners use their own order or operation identifiers.

View Payout ACH v3

Review the request, validations, and payout response.

Automatic prefunding processing

Prefunding operations now continue automatically with bank processing after receipt of funds is confirmed. The reference number generated by the provider is linked to the transaction for easier traceability.

v2.1.0

Wallets, crypto, and PIX

This release extends API v2 with wallet operations, crypto deposits and payouts, and instant PIX payments.

Wallet management

New endpoints create and list wallets, associate blockchain assets, and retrieve available balances.

View Wallet documentation

Review endpoint contracts and creation and retrieval examples.

Crypto deposits

Addresses associated with a wallet can now receive crypto deposits whose balance can be retrieved later.

View the crypto deposit flow

Learn how to obtain an address, transfer funds, and validate the deposit.

Crypto payouts

Partners can now send USDC and USDT from an internal wallet to an external address on Polygon, Ethereum, or TRON.

View Crypto Payout documentation

Review the request, response, validations, and Sandbox example.

PIX payouts

Instant BRL payments to Brazil are now available with balance or crypto conversion funding.

View PIX Payout documentation

Review the supported PIX keys and the response for each funding mode.

Crypto webhooks

Crypto deposit and withdrawal notifications now include amount, asset, blockchain, and, when applicable, walletId.

View webhook contracts

Review the deposit_crypto and withdrawal_crypto payloads.

If your integration already processes crypto webhooks, use asset and blockchain instead of relying on currency.

​New endpoints and contract changes

​New API v3 routes

​Payment statuses and errors in v3

​Changes to existing endpoints

​Client and transaction webhooks

View API v3 reference

View webhook contracts

​Virtual accounts and named collections

View virtual accounts

View collection webhooks

​Crypto, payouts, and prefunding

​Automatic crypto deposit registration

View the crypto deposit flow

​Crypto webhooks with transaction hashes

View webhook contracts

​Default network for new wallets by environment

​Controlled payout balance response

Retrieve payout balances

​Flexible references in Payout ACH v3

View Payout ACH v3

​Automatic prefunding processing

​Wallets, crypto, and PIX

​Wallet management

View Wallet documentation

​Crypto deposits

View the crypto deposit flow

​Crypto payouts

View Crypto Payout documentation

​PIX payouts

View PIX Payout documentation

​Crypto webhooks

View webhook contracts

New endpoints and contract changes

New API v3 routes

Payment statuses and errors in v3

Changes to existing endpoints

Client and transaction webhooks

Virtual accounts and named collections

Crypto, payouts, and prefunding

Automatic crypto deposit registration

Crypto webhooks with transaction hashes

Default network for new wallets by environment

Controlled payout balance response

Flexible references in Payout ACH v3

Automatic prefunding processing

Wallets, crypto, and PIX

Wallet management

Crypto deposits

Crypto payouts

PIX payouts

Crypto webhooks