Mínimos de pago

OrcaRail aplica importes mínimos de transferencia por red a los pagos. Estos mínimos se usan para validar el importe del pago y como suelo de los importes de soporte y comisión, para que las comisiones diminutas no generen polvo on-chain.

Variables de entorno

Los mínimos se configuran por tipo de cadena mediante variables de entorno. Los valores van en la unidad más pequeña de la red (lamports, wei, sats).

Variable	Cadena	Por defecto	Descripción
PAYMENTS_MIN_AMOUNT_SOLANA_LAMPORTS	Solana	890880	Transferencia mínima en lamports.
PAYMENTS_MIN_AMOUNT_EVM_WEI	EVM (Ethereum, Polygon, Base, etc.)	(ninguno)	Opcional. Si se define, mínimo en wei.
PAYMENTS_MIN_AMOUNT_BITCOIN_SATS	Bitcoin	546	Mínimo en satoshis (límite de polvo).

Si una variable no está definida para un tipo de cadena, la API no aplica ningún mínimo a esa cadena (salvo Solana y Bitcoin, que usan los valores por defecto anteriores). EVM no tiene valor por defecto; si quieres un mínimo en EVM, define PAYMENTS_MIN_AMOUNT_EVM_WEI.

Cómo se usa el mínimo

1. Validación del importe del pago

Al crear un enlace de pago o al validar el importe del pagador, la API comprueba que el importe del pago no esté por debajo del mínimo de la red del pagador.

• En los tokens nativos (por ejemplo SOL, ETH, BTC), el mínimo se compara directamente en la unidad más pequeña del token (lamports, wei, sats).
• En los tokens no nativos (por ejemplo USDC en Ethereum), el mínimo se define en la unidad nativa de la cadena; la API lo convierte a unidades del token del pagador usando el precio en USD, para aplicar el mismo mínimo económico. Si no se puede calcular el mínimo convertido (por ejemplo, porque falta el precio), puede omitirse la validación para ese token.

Si el importe está por debajo del mínimo, la API devuelve un error (por ejemplo Amount is below the minimum for this network).

2. Suelo de las comisiones de soporte y de comisión

Cuando el porcentaje de soporte o el porcentaje de comisión es mayor que 0, la API calcula el importe como porcentaje del importe original. Para evitar el polvo (salidas muy pequeñas que no son rentables o no son válidas on-chain), la API eleva cada uno de estos importes al mínimo de la red de la cadena del pagador.

• supportMinimumApplied: cuando la comisión de soporte se elevó al mínimo de la red, la cotización indica supportMinimumApplied: true. El importe de soporte real puede ser mayor que el porcentaje estricto del importe original.
• commissionMinimumApplied: cuando la comisión se elevó al mínimo de la red, la cotización indica commissionMinimumApplied: true. El importe real de la comisión puede ser mayor que el porcentaje estricto.

Así, si cobras un porcentaje pequeño (por ejemplo 0,1 %), la comisión no se queda en una fracción de céntimo por debajo del mínimo de la cadena, sino que se eleva al mínimo para que la salida sea válida.

Resumen

Caso	Comportamiento
Importe del pago demasiado bajo	Petición rechazada (error de validación).
Comisión de soporte > 0, importe calculado < mínimo	Importe de soporte = mínimo; supportMinimumApplied: true.
Comisión > 0, importe calculado < mínimo	Importe de la comisión = mínimo; commissionMinimumApplied: true.

Consulta también

• Comisiones: cómo se calculan el soporte y la comisión y cómo se incluyen en la cotización.
• Mínimos de retiro: umbral del retiro automático (independiente de los mínimos de pago).