Wallets & Withdrawals - Z2Pay Developers

As carteiras (wallets) guardam o saldo de cada recebedor (recipient). Pela API pública você consulta saldo, resumo e extrato por recebedor, e solicita/acompanha saques (payouts).

Internamente um recebedor pode ter várias carteiras físicas (uma por gateway/PSP + moeda). A API pública não expõe essa dimensão: você enxerga uma carteira “virtual” por moeda, agregando todas as carteiras físicas do recebedor. Por isso não existem endpoints por walletId — tudo é por ownerId (o recebedor) ou por recipientId.

Todos os valores monetários (availableBalance, amount, etc.) são inteiros em centavos: 152030 = R$ 1.520,30. Datas são ISO 8601 com timezone (2026-06-01T00:00:00-03:00). Veja Convenções.

Todas as requisições usam o header x-api-key. Veja Autenticação.

Endpoints

Método	Rota	Descrição
`GET`	`/wallets/owner/{ownerId}/balance`	Saldo agregado por moeda
`GET`	`/wallets/owner/{ownerId}/summary`	Resumo do extrato por período
`GET`	`/wallets/owner/{ownerId}/transactions`	Extrato paginado do recebedor
`GET`	`/withdrawals/config`	Configuração de saque (taxas e mínimo)
`GET`	`/withdrawals`	Listar saques
`GET`	`/withdrawals/{id}`	Buscar saque por ID
`POST`	`/withdrawals`	Solicitar saque
`POST`	`/withdrawals/{id}/cancel`	Cancelar saque

Saldo agregado por moeda

GET /wallets/owner/{ownerId}/balance

Retorna o saldo consolidado de todas as carteiras do recebedor, com um item por moeda.

ownerId

string

obrigatório

ID do recebedor (ex: rec_123). Vai na 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 do recebedor consultado.

balances

array

Um item por moeda em que o recebedor tem carteira.

Mostrar campos de cada saldo

currency

string

Moeda do saldo (ISO 4217, ex: BRL).

availableBalance

integer

Saldo liberado, em centavos.

pendingBalance

integer

Saldo a liberar (ex: parcelas de cartão com liberação futura), em centavos.

blockedBalance

integer

Saldo bloqueado (ex: chargebacks em disputa, refunds pendentes), em centavos.

withdrawableBalance

integer

Saldo efetivamente sacável, em centavos.

Resumo do extrato por período

GET /wallets/owner/{ownerId}/summary

Retorna totais do extrato agrupados por moeda e tipo de lançamento (entradas, saídas e net). Aceita os mesmos filtros do extrato, sem paginação.

ownerId

string

obrigatório

ID do recebedor. Vai na URL.

Filtros (query params)

type

string

Filtra por tipo de lançamento.

source

string

Filtra pela origem do lançamento.

currency

string

Filtra por moeda (ISO 4217).

releaseStatus

string

Status de liberação. Valores aceitos: released ou pending.

startDate

string

Início do período, ISO 8601 com timezone. Ex: 2026-06-01T00:00:00-03:00.

endDate

string

Fim do período, ISO 8601 com timezone.

Datas devem ser ISO 8601 com offset de timezone. Strings localizadas (01/06/2026) ou date-only (2026-06-01) são rejeitadas com 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 do recebedor consultado.

data

array

Um item por moeda com o resumo do período. Cada item tem currency, byType (lista de { type, total, credits, debits, count }), totalCredits, totalDebits e net. credits e debits são separados pelo sinal do lançamento; net = totalCredits + totalDebits. Todos os valores em centavos.

Extrato do recebedor

GET /wallets/owner/{ownerId}/transactions

Retorna o extrato paginado, consolidando todas as carteiras do recebedor. Cada lançamento traz sua moeda.

ownerId

string

obrigatório

ID do recebedor. Vai na URL.

Paginação (query params)

page

integer

padrão:"1"

Página atual.

limit

integer

padrão:"20"

Itens por página.

Filtros (query params)

Os filtros são os mesmos do resumo: type, source, currency, releaseStatus (released ou pending), startDate e endDate (ISO 8601 com timezone). Todos são opcionais.

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
  }
}

A resposta é o envelope de paginação padrão da Core API: data (lista de lançamentos) + pagination. Veja Convenções para o formato completo.

Saques (payouts)

O saque é solicitado por recebedor + moeda: o sistema agrega o saldo sacável de todas as carteiras daquela moeda. O fluxo de status é:

requested → approved → processing → paid
          ↘ rejected
          ↘ cancelled

Um saque criado pela API entra como requested e aguarda aprovação manual no dashboard antes de ser processado.

Configuração de saque

GET /withdrawals/config

Retorna as taxas (percentual e fixa) e o valor mínimo de saque da sua company, opcionalmente por moeda.

currency

string

Moeda no formato ISO 4217 (exatamente 3 letras, ex: 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

Taxa percentual aplicada sobre o valor do saque.

feeFixed

integer

Taxa fixa por saque, em centavos.

minimumAmount

integer

Valor mínimo de saque, em centavos.

Listar saques

GET /withdrawals

Retorna a lista paginada de saques da sua company.

status

string

Filtra por status. Valores possíveis: requested, approved, processing, paid, cancelled, rejected, failed. Opcional.

page

integer

padrão:"1"

Página atual.

limit

integer

padrão:"20"

Itens 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 saque por ID

GET /withdrawals/{id}

Retorna os dados completos de um saque, incluindo o histórico de status.

string

obrigatório

ID do saque. Vai na 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"
}

Se o saque não existir (ou não pertencer à sua company), o endpoint retorna 404. Veja Erros.

Solicitar saque

POST /withdrawals

Solicita um saque por recipientId, agregando o saldo de todas as carteiras daquela moeda. O saque entra como requested e aguarda aprovação. Retorna 201.

recipientId

string

obrigatório

ID do recebedor que vai sacar.

amount

integer

obrigatório

Valor do saque em centavos. Inteiro, mínimo 1.

currency

string

Moeda no formato ISO 4217 (exatamente 3 letras). Opcional — quando omitido, o default é BRL.

Este endpoint suporta idempotência. Envie o header Idempotency-Key com uma chave única por solicitação para evitar saques duplicados em caso de retry. Veja Convenções.

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"
}

O saque retornado traz walletId (a carteira física debitada — escolhida automaticamente quando há mais de uma na moeda), amount (bruto), fee e netAmount (amount - fee). O recebedor informado no request não é ecoado de volta no corpo.

Retorna 409 quando o saldo é insuficiente, o valor está abaixo do mínimo de saque, ou não há nenhuma carteira ativa na moeda informada. O corpo do erro segue o formato padrão — veja Erros.

Cancelar saque

POST /withdrawals/{id}/cancel

Cancela um saque que ainda não foi aprovado (apenas status requested).

string

obrigatório

ID do saque a cancelar. Vai na URL.

reason

string

Motivo do cancelamento. Opcional (mínimo 1 caractere quando enviado).

Suporta idempotência via 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"
}

Status de erro:

404 — saque não encontrado.
409 — o saque não pode ser cancelado no status atual (já saiu de requested).

Veja os formatos em Erros.

Veja também

Recebedores

Cadastre os recebedores donos das carteiras.

Splits

Como o saldo entra nas carteiras a partir das vendas.

Liquidação

Quando e como o saldo é liberado para saque.

Webhooks

Receba eventos de saque (withdrawal.*) no seu sistema.

​Endpoints

​Saldo agregado por moeda

​Resumo do extrato por período

​Filtros (query params)

​Extrato do recebedor

​Paginação (query params)

​Filtros (query params)

​Saques (payouts)

​Configuração de saque

​Listar saques

​Buscar saque por ID

​Solicitar saque

​Cancelar saque

​Veja também

Recebedores

Splits

Liquidação

Webhooks

Endpoints

Saldo agregado por moeda

Resumo do extrato por período

Filtros (query params)

Extrato do recebedor

Paginação (query params)

Filtros (query params)

Saques (payouts)

Configuração de saque

Listar saques

Buscar saque por ID

Solicitar saque

Cancelar saque

Veja também