Saltar al contenido principal
Esta sección explica el camino del dinero dentro de Z2Pay: desde el momento en que se paga un cobro hasta que el valor queda disponible para retiro. Antes de integrar el split o consultar saldos, vale la pena entender cómo se representa cada valor y por dónde pasa.
Esta página es conceptual. Los endpoints concretos están en las páginas Tarifas, Split y Liquidación.

​
Dos reglas que aplican a todo

Valores en centavos

Todo valor monetario es un entero en centavos. R$ 10,00 se envía y se retorna como 1000. Para mostrar, divida por 100. Nunca envíe decimales (10.00) en campos de valor.

Moneda BRL

La moneda predeterminada es BRL (Real brasileño). Cuando aparece un campo currency, sigue el estándar ISO 4217 con 3 letras (ej.: "BRL").
Si envía 1050 pensando en “R1.050,00",Z2Payentenderaˊ∗∗R 1.050,00", Z2Pay entenderá **R 10,50**. Siempre en centavos. Consulte la página de convenciones para los detalles de formato.

​
El camino del dinero

El flujo estándar de una venta hasta el retiro tiene cinco etapas:
1

Cobro pagado

El cliente paga una transacción (tarjeta, Pix o boleto). El valor bruto entra al sistema en centavos. Consulte Transacciones y Pagos.
2

Tarifa aplicada

Sobre el valor bruto se aplican las tarifas de la plataforma (tarifa de procesamiento, tarifa fija, etc.). Lo que queda es el valor neto a distribuir. Consulte Tarifas.
3

Split entre receptores

Si la transacción tiene un split configurado, el valor neto se reparte entre los receptores según la configuración (por porcentaje o valor fijo). Consulte Split.
4

Crédito en la billetera

Cada parte del split se convierte en un crédito en la billetera (wallet) del receptor. El crédito puede quedar pendiente (pending) hasta pasar el período de liberación, o ya liberado (released). Consulte Liquidación.
5

Retiro

Con saldo liberado en la billetera, el receptor solicita un retiro (withdrawal) hacia su cuenta bancaria. Consulte Liquidación.

​
Conceptos clave

El valor bruto es lo que pagó el cliente. El valor neto es lo que queda después de las tarifas y es el valor efectivamente distribuido en el split. Ambos son enteros en centavos.
Un split define cómo se divide el valor de una transacción entre los receptores. Cada elemento del split apunta a un recipientId y tiene un value más un valueType que indica si ese valor es porcentual (percentage) o valor fijo en centavos (fixed).Reglas importantes de la configuración de split:
  • Todos los elementos porcentuales suman 100%.
  • Exactamente 1 elemento asume la tarifa de procesamiento (processingFee: true).
  • Exactamente 1 elemento es el responsable (liable: true).
  • El tipo de cada elemento (type) puede ser sale, interest o platform_fee — el valor predeterminado es sale.
Puede usar una configuración de split reutilizable (split config) o enviar un split inline al crear la transacción. Detalles y ejemplos en Split y Split (Core API).
La billetera es donde se acumula el saldo de un receptor. Cada movimiento aparece en el extracto de la billetera (wallet transactions), con un estado de liberación que puede ser pending (aún no liberado) o released (disponible). Detalles en Billeteras (Core API).
El retiro transfiere el saldo liberado de la billetera a la cuenta bancaria del receptor. El valor del retiro es un entero en centavos (mínimo 1) y el currency es opcional (3 letras, ISO 4217). Detalles y endpoints en Liquidación y Billeteras (Core API).

​
Ejemplo del flujo en números

Una venta de R100,00∗∗(‘10000‘centavos)conunatarifatotalde∗∗R 100,00** (`10000` centavos) con una tarifa total de **R 5,00 (500) y un split de 70% / 30% entre dos receptores queda así: 
{
  "grossAmount": 10000,
  "totalFees": 500,
  "netAmount": 9500,
  "split": [
    { "recipientId": "rec_1a2b3c", "valueType": "percentage", "value": 70, "netAmount": 6650 },
    { "recipientId": "rec_4d5e6f", "valueType": "percentage", "value": 30, "netAmount": 2850 }
  ]
}
Los nombres de campo anteriores son ilustrativos para explicar el concepto. Los campos exactos de cada respuesta están en las páginas de referencia de cada recurso (Transacciones, Split, Billeteras).

​
Próximos pasos

Tarifas

Cómo se aplican las tarifas sobre el valor bruto.

Split

Configurar el prorrateo entre receptores.

Liquidación

Billetera, liberación de saldo y retiro.

Receptores

Registrar quién recibe en el split.