Liquidación y retiro - Z2Pay Developers

Cuando una transacción es pagada, el valor (descontadas comisiones y splits) es acreditado en la billetera (wallet) del beneficiario. Ese saldo pasa por etapas — pending, available y blocked — hasta quedar disponible para retiro. Esta página explica ese ciclo y los endpoints para consultar saldo y solicitar retiros.

Las billeteras están organizadas por beneficiario (recipient) y por moneda. La API agrega todas las billeteras internas de un beneficiario en una vista única por moneda — no es necesario manejar IDs de billeteras individuales.

Del pago al saldo

Pago confirmado

Una transacción es pagada. El valor neto (después de comisiones y split) es acreditado en la billetera del beneficiario.

Saldo a liberar (pending)

Inmediatamente después del pago, el valor entra como pending (a liberar). Aún no puede ser retirado.

Saldo disponible (available)

Tras el período de liberación, el valor pasa de pending a available (disponible).

Solicitud de retiro

Usted solicita un retiro del saldo retirable. El retiro entra como requested y aguarda aprobación. Ver flujo de retiro.

Etapas del saldo

La consulta de saldo devuelve cuatro valores por moneda, todos en centavos (enteros):

availableBalance

integer

Saldo disponible: valor ya liberado, suma de todas las billeteras de la moneda.

pendingBalance

integer

Saldo a liberar (pending): valor acreditado pero aún en período de liberación. No puede ser retirado.

blockedBalance

integer

Saldo bloqueado: valor retenido (ej.: por disputa/chargeback o reserva). Reduce lo que puede ser retirado.

withdrawableBalance

integer

Saldo retirable: cuánto puede ser retirado en este momento. Se calcula a partir de available - blocked, aplicando el límite porcentual de retiro configurado para su cuenta en la moneda. Es este valor el que debe comparar antes de llamar al retiro.

Utilice siempre withdrawableBalance para decidir el valor de un retiro. availableBalance no descuenta el bloqueo ni el límite porcentual de la cuenta.

Endpoints

Todas las solicitudes utilizan el header x-api-key (ver Autenticación).

Método	Ruta	Descripción
`GET`	`/wallets/owner/{ownerId}/balance`	Saldo agregado por moneda del beneficiario
`GET`	`/withdrawals/config`	Comisiones y valor mínimo de retiro
`POST`	`/withdrawals`	Solicitar un retiro
`GET`	`/withdrawals`	Listar retiros (paginado)
`GET`	`/withdrawals/{id}`	Buscar un retiro por ID
`POST`	`/withdrawals/{id}/cancel`	Cancelar un retiro aún no aprobado

El extracto detallado de la billetera (movimientos, resumen por período) se cubre en Billeteras.

Consultar saldo

ownerId

string

requerido

ID del beneficiario (recipient), en formato rec_....

Requisição

curl https://api.sandbox.z2pay.com/wallets/owner/rec_8a1f2c3d4e5f/balance \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Resposta 200

{
  "recipientId": "rec_8a1f2c3d4e5f",
  "balances": [
    {
      "currency": "BRL",
      "availableBalance": 150000,
      "pendingBalance": 32000,
      "blockedBalance": 0,
      "withdrawableBalance": 150000
    }
  ]
}

balances trae un ítem por moneda. Si el beneficiario no tiene billeteras, el array viene vacío. Los valores están en centavos: 150000 = R$ 1.500,00.

Configuración de retiro

Antes de solicitar un retiro, consulte la configuración para conocer la comisión y el valor mínimo. Los valores monetarios están en centavos.

currency

string

Filtra la configuración por moneda (ISO 4217, 3 letras, ej.: BRL). Opcional.

Requisição

curl "https://api.sandbox.z2pay.com/withdrawals/config?currency=BRL" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Resposta 200

{
  "feePercentage": 0,
  "feeFixed": 367,
  "minimumAmount": 1000
}

feePercentage

number

Porcentaje de la comisión de retiro aplicada sobre el valor solicitado.

feeFixed

integer

Comisión fija de retiro, en centavos (ej.: 367 = R$ 3,67).

minimumAmount

integer

Valor mínimo para solicitar un retiro, en centavos. Las solicitudes por debajo de este valor son rechazadas.

Solicitar retiro

Solicita un retiro para un beneficiario en una moneda. El retiro agrega el saldo de todas las billeteras de la moneda y entra con status requested, aguardando aprobación.

Este endpoint devuelve 201 Created y acepta el header opcional Idempotency-Key para evitar retiros duplicados en caso de reintento. Ver Convenciones.

recipientId

string

requerido

ID del beneficiario (recipient), formato rec_....

amount

integer

requerido

Valor bruto del retiro, en centavos. Debe ser entero y mayor que 0.

currency

string

predeterminado:"BRL"

Moneda del retiro (ISO 4217, exactamente 3 letras, ej.: BRL). Opcional — cuando se omite, usa BRL.

Requisição

curl -X POST https://api.sandbox.z2pay.com/withdrawals \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 9c1e7b40-2f3a-4d18-9a77-6b2c1d4e5f60" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientId": "rec_8a1f2c3d4e5f",
    "amount": 50000,
    "currency": "BRL"
  }'

Resposta 201

{
  "id": "wdr_3b9c1a2d4e6f",
  "walletId": "wlt_7d2e1f0a3b4c",
  "tenantId": "comp_1a2b3c4d5e6f",
  "amount": 50000,
  "currency": "BRL",
  "fee": 367,
  "netAmount": 49633,
  "status": "requested",
  "bankAccountId": null,
  "paidAt": null,
  "pspTransferId": null,
  "statusHistory": [
    {
      "status": "requested",
      "changedBy": "api",
      "changedAt": "2026-06-24T13:45:00.000Z"
    }
  ],
  "image": null,
  "createdAt": "2026-06-24T13:45:00.000Z",
  "updatedAt": "2026-06-24T13:45:00.000Z"
}

El netAmount es el valor que el beneficiario efectivamente recibe: amount - fee. La comisión (fee) se calcula en el momento de la solicitud a partir de la configuración de retiro.

Si el saldo retirable es insuficiente, el valor está por debajo del mínimo, o no hay billetera activa en la moneda, la API devuelve 409 Conflict. Verifique el saldo (withdrawableBalance) y el mínimo (minimumAmount) antes de solicitar. Ver Errores.

Flujo de retiro

Un retiro recorre los siguientes estados:

requested → approved → processing → paid

Caminos alternativos: cancelled (cancelado por el comerciante antes de la aprobación), rejected (rechazado en el análisis) y failed (falla en el procesamiento).

requested

Estado inicial inmediatamente después de la solicitud. Aguarda aprobación manual. Es el único estado en el que el retiro puede ser cancelado vía API.

approved

El retiro fue aprobado en el análisis y continúa hacia el procesamiento.

processing

El pago está siendo ejecutado hacia el destino bancario.

paid

Retiro completado. El campo paidAt es completado y pspTransferId puede traer la referencia de la transferencia.

cancelled / rejected / failed

cancelled: cancelado por el comerciante mientras aún estaba en requested. rejected: rechazado en el análisis. failed: falla durante el procesamiento.

Haga seguimiento de las transiciones de retiro en tiempo real suscribiéndose a los eventos de webhook (withdrawal.requested, withdrawal.paid, withdrawal.rejected). Ver Webhooks.

Listar retiros

Devuelve la lista paginada de retiros de la cuenta, con filtro opcional por estado.

status

string

Filtra por estado. Valores: requested, approved, processing, paid, cancelled, rejected, failed. Opcional.

page

integer

predeterminado:"1"

Página de la paginación.

limit

integer

predeterminado:"20"

Cantidad de ítems por página (máximo 100).

Requisição

curl "https://api.sandbox.z2pay.com/withdrawals?status=paid&page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Resposta 200

{
  "data": [
    {
      "id": "wdr_3b9c1a2d4e6f",
      "walletId": "wlt_7d2e1f0a3b4c",
      "amount": 50000,
      "currency": "BRL",
      "fee": 367,
      "netAmount": 49633,
      "status": "paid",
      "paidAt": "2026-06-23T18:10:00.000Z",
      "createdAt": "2026-06-23T13:45:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

Buscar retiro por ID

Devuelve los datos completos de un retiro, incluyendo el historial de estados (statusHistory).

string

requerido

ID del retiro, formato wdr_....

Requisição

curl https://api.sandbox.z2pay.com/withdrawals/wdr_3b9c1a2d4e6f \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Resposta 200

{
  "id": "wdr_3b9c1a2d4e6f",
  "walletId": "wlt_7d2e1f0a3b4c",
  "tenantId": "comp_1a2b3c4d5e6f",
  "amount": 50000,
  "currency": "BRL",
  "fee": 367,
  "netAmount": 49633,
  "status": "paid",
  "bankAccountId": null,
  "paidAt": "2026-06-23T18:10:00.000Z",
  "pspTransferId": "psp_xfer_2c4e6a8b0d1f",
  "statusHistory": [
    { "status": "requested", "changedBy": null, "changedAt": "2026-06-23T13:45:00.000Z" },
    { "status": "approved", "changedBy": "user_9f8e7d6c5b4a", "changedAt": "2026-06-23T15:00:00.000Z" },
    { "status": "processing", "changedBy": null, "changedAt": "2026-06-23T17:30:00.000Z" },
    { "status": "paid", "changedBy": null, "changedAt": "2026-06-23T18:10:00.000Z" }
  ],
  "image": null,
  "createdAt": "2026-06-23T13:45:00.000Z",
  "updatedAt": "2026-06-23T18:10:00.000Z"
}

Si el retiro no existe, la API devuelve 404 Not Found. Ver Errores.

Cancelar retiro

Cancela un retiro únicamente mientras está en requested (aún no aprobado).

Este endpoint acepta el header opcional Idempotency-Key.

string

requerido

ID del retiro, formato wdr_....

reason

string

Motivo de la cancelación (mínimo 1 carácter). Opcional — cuando se omite, se registra un motivo predeterminado.

Requisição

curl -X POST https://api.sandbox.z2pay.com/withdrawals/wdr_3b9c1a2d4e6f/cancel \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Solicitado pelo lojista" }'

Resposta 200

{
  "id": "wdr_3b9c1a2d4e6f",
  "status": "cancelled",
  "amount": 50000,
  "currency": "BRL",
  "fee": 367,
  "netAmount": 49633,
  "updatedAt": "2026-06-24T14:02:00.000Z"
}

Si el retiro no se encuentra, devuelve 404; si el retiro no puede ser cancelado en el estado actual (ej.: ya aprobado o pagado) devuelve 409. Ver Errores.

Probar en sandbox

En el sandbox puede simular la liberación de saldo y la liquidación de retiros sin mover dinero real.

Visión general del sandbox

Cómo funciona el entorno de pruebas.

Simular eventos

Fuerce transiciones para probar el flujo de retiro.

Ver también

Billeteras

Saldo, extracto y resumen por período.

Comisiones

Cómo se calculan las comisiones.

Split

División de valores entre beneficiarios.

Webhooks

Reciba notificaciones de retiro en tiempo real.

​Del pago al saldo

​Etapas del saldo

​Endpoints

​Consultar saldo

​Configuración de retiro

​Solicitar retiro

​Flujo de retiro

​Listar retiros

​Buscar retiro por ID

​Cancelar retiro

​Probar en sandbox

Visión general del sandbox

Simular eventos

​Ver también

Billeteras

Comisiones

Split

Webhooks

Del pago al saldo

Etapas del saldo

Endpoints

Consultar saldo

Configuración de retiro

Solicitar retiro

Flujo de retiro

Listar retiros

Buscar retiro por ID

Cancelar retiro

Probar en sandbox

Ver también