Wallets & Withdrawals - Z2Pay Developers

Las billeteras (wallets) almacenan el saldo de cada beneficiario (recipient). A través de la API pública puedes consultar el saldo, el resumen y el extracto por beneficiario, y solicitar o hacer seguimiento de retiros (payouts).

Internamente, un beneficiario puede tener varias billeteras físicas (una por gateway/PSP + moneda). La API pública no expone esa dimensión: verás una billetera “virtual” por moneda, que agrega todas las billeteras físicas del beneficiario. Por eso no existen endpoints por walletId — todo se accede por ownerId (el beneficiario) o por recipientId.

Todos los valores monetarios (availableBalance, amount, etc.) son enteros en centavos: 152030 = R$ 1.520,30. Las fechas son ISO 8601 con timezone (2026-06-01T00:00:00-03:00). Consulta Convenciones.

Todas las solicitudes utilizan el header x-api-key. Consulta Autenticación.

Endpoints

Método	Ruta	Descripción
`GET`	`/wallets/owner/{ownerId}/balance`	Saldo agregado por moneda
`GET`	`/wallets/owner/{ownerId}/summary`	Resumen del extracto por período
`GET`	`/wallets/owner/{ownerId}/transactions`	Extracto paginado del beneficiario
`GET`	`/withdrawals/config`	Configuración de retiro (tarifas y mínimo)
`GET`	`/withdrawals`	Listar retiros
`GET`	`/withdrawals/{id}`	Buscar retiro por ID
`POST`	`/withdrawals`	Solicitar retiro
`POST`	`/withdrawals/{id}/cancel`	Cancelar retiro

Saldo agregado por moneda

GET /wallets/owner/{ownerId}/balance

Devuelve el saldo consolidado de todas las billeteras del beneficiario, con un ítem por moneda.

ownerId

string

requerido

ID del beneficiario (ej: rec_123). Se envía en la URL.

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

{
  "recipientId": "rec_123",
  "balances": [
    {
      "currency": "BRL",
      "availableBalance": 152030,
      "pendingBalance": 40000,
      "blockedBalance": 0,
      "withdrawableBalance": 152030
    }
  ]
}

recipientId

string

ID del beneficiario consultado.

balances

array

Un ítem por moneda en la que el beneficiario tiene billetera.

Mostrar campos de cada saldo

currency

string

Moneda del saldo (ISO 4217, ej: BRL).

availableBalance

integer

Saldo disponible, en centavos.

pendingBalance

integer

Saldo por liberar (ej: cuotas de tarjeta con liberación futura), en centavos.

blockedBalance

integer

Saldo bloqueado (ej: contracargos en disputa, reembolsos pendientes), en centavos.

withdrawableBalance

integer

Saldo efectivamente retirable, en centavos.

Resumen del extracto por período

GET /wallets/owner/{ownerId}/summary

Devuelve los totales del extracto agrupados por moneda y tipo de movimiento (entradas, salidas y neto). Acepta los mismos filtros que el extracto, sin paginación.

ownerId

string

requerido

ID del beneficiario. Se envía en la URL.

Filtros (query params)

type

string

Filtra por tipo de movimiento.

source

string

Filtra por el origen del movimiento.

currency

string

Filtra por moneda (ISO 4217).

releaseStatus

string

Estado de liberación. Valores aceptados: released o pending.

startDate

string

Inicio del período, ISO 8601 con timezone. Ej: 2026-06-01T00:00:00-03:00.

endDate

string

Fin del período, ISO 8601 con timezone.

Las fechas deben ser ISO 8601 con offset de timezone. Las cadenas localizadas (01/06/2026) o solo con fecha (2026-06-01) son rechazadas con 400.

curl "https://api.sandbox.z2pay.com/wallets/owner/rec_123/summary?startDate=2026-06-01T00:00:00-03:00&endDate=2026-06-30T23:59:59-03:00" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "recipientId": "rec_123",
  "data": [
    {
      "currency": "BRL",
      "byType": [
        { "type": "sale", "total": 250000, "credits": 250000, "debits": 0, "count": 42 },
        { "type": "fee", "total": -12500, "credits": 0, "debits": -12500, "count": 42 },
        { "type": "withdrawal", "total": -80000, "credits": 0, "debits": -80000, "count": 2 }
      ],
      "totalCredits": 250000,
      "totalDebits": -92500,
      "net": 157500
    }
  ]
}

recipientId

string

ID del beneficiario consultado.

data

array

Un ítem por moneda con el resumen del período. Cada ítem contiene currency, byType (lista de { type, total, credits, debits, count }), totalCredits, totalDebits y net. credits y debits se separan por el signo del movimiento; net = totalCredits + totalDebits. Todos los valores en centavos.

Extracto del beneficiario

GET /wallets/owner/{ownerId}/transactions

Devuelve el extracto paginado, consolidando todas las billeteras del beneficiario. Cada movimiento incluye su moneda.

ownerId

string

requerido

ID del beneficiario. Se envía en la URL.

Paginación (query params)

page

integer

predeterminado:"1"

Página actual.

limit

integer

predeterminado:"20"

Ítems por página.

Filtros (query params)

Los filtros son los mismos que los del resumen: type, source, currency, releaseStatus (released o pending), startDate y endDate (ISO 8601 con timezone). Todos son opcionales.

curl "https://api.sandbox.z2pay.com/wallets/owner/rec_123/transactions?page=1&limit=20&releaseStatus=released" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "currency": "BRL",
      "type": "sale",
      "amount": 250000,
      "createdAt": "2026-06-10T14:32:00-03:00"
    },
    {
      "currency": "BRL",
      "type": "fee",
      "amount": -12500,
      "createdAt": "2026-06-10T14:32:00-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 84,
    "totalPages": 5
  }
}

La respuesta sigue el sobre de paginación estándar de la Core API: data (lista de movimientos) + pagination. Consulta Convenciones para el formato completo.

Retiros (payouts)

El retiro se solicita por beneficiario + moneda: el sistema agrega el saldo retirable de todas las billeteras de esa moneda. El flujo de estados es:

requested → approved → processing → paid
          ↘ rejected
          ↘ cancelled

Un retiro creado por la API entra como requested y espera aprobación manual en el dashboard antes de ser procesado.

Configuración de retiro

GET /withdrawals/config

Devuelve las tarifas (porcentual y fija) y el monto mínimo de retiro de tu company, opcionalmente por moneda.

currency

string

Moneda en formato ISO 4217 (exactamente 3 letras, ej: BRL). Opcional.

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

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

feePercentage

number

Tarifa porcentual aplicada sobre el monto del retiro.

feeFixed

integer

Tarifa fija por retiro, en centavos.

minimumAmount

integer

Monto mínimo de retiro, en centavos.

Listar retiros

GET /withdrawals

Devuelve la lista paginada de retiros de tu company.

status

string

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

page

integer

predeterminado:"1"

Página actual.

limit

integer

predeterminado:"20"

Ítems por página.

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

{
  "data": [
    {
      "id": "wdr_8h2k9x",
      "walletId": "wlt_a1b2c3",
      "amount": 50000,
      "currency": "BRL",
      "fee": 367,
      "netAmount": 49633,
      "status": "requested",
      "createdAt": "2026-06-20T09:00:00-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "totalPages": 1
  }
}

Buscar retiro por ID

GET /withdrawals/{id}

Devuelve los datos completos de un retiro, incluido el historial de estados.

string

requerido

ID del retiro. Se envía en la URL.

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

{
  "id": "wdr_8h2k9x",
  "walletId": "wlt_a1b2c3",
  "amount": 50000,
  "currency": "BRL",
  "fee": 367,
  "netAmount": 49633,
  "status": "requested",
  "bankAccountId": "rba_123",
  "paidAt": null,
  "pspTransferId": null,
  "statusHistory": [
    { "status": "requested", "changedBy": "api", "changedAt": "2026-06-20T09:00:00-03:00" }
  ],
  "createdAt": "2026-06-20T09:00:00-03:00"
}

Si el retiro no existe (o no pertenece a tu company), el endpoint devuelve 404. Consulta Errores.

Solicitar retiro

POST /withdrawals

Solicita un retiro por recipientId, agregando el saldo de todas las billeteras de esa moneda. El retiro entra como requested y espera aprobación. Devuelve 201.

recipientId

string

requerido

ID del beneficiario que realizará el retiro.

amount

integer

requerido

Monto del retiro en centavos. Entero, mínimo 1.

currency

string

Moneda en formato ISO 4217 (exactamente 3 letras). Opcional — cuando se omite, el valor por defecto es BRL.

Este endpoint soporta idempotencia. Envía el header Idempotency-Key con una clave única por solicitud para evitar retiros duplicados en caso de reintento. Consulta Convenciones.

curl -X POST https://api.sandbox.z2pay.com/withdrawals \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 0c8b1f2a-7e4d-4a91-9b3c-2f6e5d4c3b2a" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientId": "rec_123",
    "amount": 50000,
    "currency": "BRL"
  }'

{
  "id": "wdr_8h2k9x",
  "walletId": "wlt_a1b2c3",
  "amount": 50000,
  "currency": "BRL",
  "fee": 367,
  "netAmount": 49633,
  "status": "requested",
  "bankAccountId": "rba_123",
  "paidAt": null,
  "pspTransferId": null,
  "statusHistory": [
    { "status": "requested", "changedBy": "api", "changedAt": "2026-06-20T09:00:00-03:00" }
  ],
  "createdAt": "2026-06-20T09:00:00-03:00"
}

El retiro devuelto incluye walletId (la billetera física debitada — elegida automáticamente cuando hay más de una en la moneda), amount (bruto), fee y netAmount (amount - fee). El beneficiario informado en el request no se devuelve en el cuerpo de la respuesta.

Devuelve 409 cuando el saldo es insuficiente, el monto está por debajo del mínimo de retiro, o no existe ninguna billetera activa en la moneda indicada. El cuerpo del error sigue el formato estándar — consulta Errores.

Cancelar retiro

POST /withdrawals/{id}/cancel

Cancela un retiro que aún no ha sido aprobado (solo en estado requested).

string

requerido

ID del retiro a cancelar. Se envía en la URL.

reason

string

Motivo de la cancelación. Opcional (mínimo 1 carácter cuando se envía).

Soporta idempotencia mediante el header Idempotency-Key.

curl -X POST https://api.sandbox.z2pay.com/withdrawals/wdr_8h2k9x/cancel \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 4d3c2b1a-9f8e-4d7c-8b6a-5e4f3d2c1b0a" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Solicitado pelo recebedor" }'

{
  "id": "wdr_8h2k9x",
  "walletId": "wlt_a1b2c3",
  "amount": 50000,
  "currency": "BRL",
  "fee": 367,
  "netAmount": 49633,
  "status": "cancelled",
  "createdAt": "2026-06-20T09:00:00-03:00"
}

Códigos de error:

404 — retiro no encontrado.
409 — el retiro no puede cancelarse en el estado actual (ya salió de requested).

Consulta los formatos en Errores.

Ver también

Beneficiarios

Registra los beneficiarios propietarios de las billeteras.

Splits

Cómo el saldo ingresa a las billeteras a partir de las ventas.

Liquidación

Cuándo y cómo se libera el saldo para retiro.

Webhooks

Recibe eventos de retiro (withdrawal.*) en tu sistema.

​Endpoints

​Saldo agregado por moneda

​Resumen del extracto por período

​Filtros (query params)

​Extracto del beneficiario

​Paginación (query params)

​Filtros (query params)

​Retiros (payouts)

​Configuración de retiro

​Listar retiros

​Buscar retiro por ID

​Solicitar retiro

​Cancelar retiro

​Ver también

Beneficiarios

Splits

Liquidación

Webhooks

Endpoints

Saldo agregado por moneda

Resumen del extracto por período

Filtros (query params)

Extracto del beneficiario

Paginación (query params)

Filtros (query params)

Retiros (payouts)

Configuración de retiro

Listar retiros

Buscar retiro por ID

Solicitar retiro

Cancelar retiro

Ver también