Wallets & Withdrawals - Z2Pay Developers

Wallets store the balance for each recipient (recipient). Through the public API you can query balance, summary, and statement by recipient, and request/track payouts (withdrawals).

Internally, a recipient may have multiple physical wallets (one per gateway/PSP + currency). The public API does not expose this dimension: you see a single “virtual” wallet per currency, aggregating all of the recipient’s physical wallets. That is why there are no endpoints by walletId — everything is by ownerId (the recipient) or recipientId.

All monetary values (availableBalance, amount, etc.) are integers in cents: 152030 = BRL 1,520.30. Dates are ISO 8601 with timezone (2026-06-01T00:00:00-03:00). See Conventions.

All requests use the x-api-key header. See Authentication.

Endpoints

Method	Route	Description
`GET`	`/wallets/owner/{ownerId}/balance`	Aggregated balance by currency
`GET`	`/wallets/owner/{ownerId}/summary`	Statement summary by period
`GET`	`/wallets/owner/{ownerId}/transactions`	Paginated recipient statement
`GET`	`/withdrawals/config`	Withdrawal configuration (fees and minimum)
`GET`	`/withdrawals`	List withdrawals
`GET`	`/withdrawals/{id}`	Retrieve withdrawal by ID
`POST`	`/withdrawals`	Request a withdrawal
`POST`	`/withdrawals/{id}/cancel`	Cancel a withdrawal

Aggregated balance by currency

GET /wallets/owner/{ownerId}/balance

Returns the consolidated balance of all the recipient’s wallets, with one item per currency.

ownerId

string

required

Recipient ID (e.g. rec_123). Passed in the 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 of the queried recipient.

balances

array

One item per currency in which the recipient has a wallet.

Show balance fields

currency

string

Balance currency (ISO 4217, e.g. BRL).

availableBalance

integer

Released balance, in cents.

pendingBalance

integer

Balance pending release (e.g. credit card installments with future release dates), in cents.

blockedBalance

integer

Blocked balance (e.g. chargebacks under dispute, pending refunds), in cents.

withdrawableBalance

integer

Balance effectively available for withdrawal, in cents.

Statement summary by period

GET /wallets/owner/{ownerId}/summary

Returns statement totals grouped by currency and entry type (credits, debits, and net). Accepts the same filters as the statement endpoint, without pagination.

ownerId

string

required

Recipient ID. Passed in the URL.

Filters (query params)

type

string

Filters by entry type.

source

string

Filters by entry source.

currency

string

Filters by currency (ISO 4217).

releaseStatus

string

Release status. Accepted values: released or pending.

startDate

string

Start of the period, ISO 8601 with timezone. E.g. 2026-06-01T00:00:00-03:00.

endDate

string

End of the period, ISO 8601 with timezone.

Dates must be ISO 8601 with a timezone offset. Localized strings (01/06/2026) or date-only values (2026-06-01) will be rejected with a 400 error.

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 of the queried recipient.

data

array

One item per currency with the period summary. Each item contains currency, byType (a list of { type, total, credits, debits, count }), totalCredits, totalDebits, and net. credits and debits are separated by the sign of the entry; net = totalCredits + totalDebits. All values in cents.

Recipient statement

GET /wallets/owner/{ownerId}/transactions

Returns the paginated statement, consolidating all of the recipient’s wallets. Each entry includes its currency.

ownerId

string

required

Recipient ID. Passed in the URL.

Pagination (query params)

page

integer

default:"1"

Current page.

limit

integer

default:"20"

Items per page.

Filters (query params)

The filters are the same as the summary endpoint: type, source, currency, releaseStatus (released or pending), startDate, and endDate (ISO 8601 with timezone). All are optional.

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

The response uses the Core API’s standard pagination envelope: data (list of entries) + pagination. See Conventions for the full format.

Withdrawals (payouts)

A withdrawal is requested by recipient + currency: the system aggregates the withdrawable balance from all wallets in that currency. The status flow is:

requested → approved → processing → paid
          ↘ rejected
          ↘ cancelled

A withdrawal created via the API enters as requested and awaits manual approval in the dashboard before being processed.

Withdrawal configuration

GET /withdrawals/config

Returns the fee rates (percentage and fixed) and the minimum withdrawal amount for your company, optionally filtered by currency.

currency

string

Currency in ISO 4217 format (exactly 3 letters, e.g. BRL). Optional.

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

Percentage fee applied to the withdrawal amount.

feeFixed

integer

Fixed fee per withdrawal, in cents.

minimumAmount

integer

Minimum withdrawal amount, in cents.

List withdrawals

GET /withdrawals

Returns the paginated list of withdrawals for your company.

status

string

Filters by status. Possible values: requested, approved, processing, paid, cancelled, rejected, failed. Optional.

page

integer

default:"1"

Current page.

limit

integer

default:"20"

Items per page.

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

Retrieve withdrawal by ID

GET /withdrawals/{id}

Returns the full details of a withdrawal, including the status history.

string

required

Withdrawal ID. Passed in the 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"
}

If the withdrawal does not exist (or does not belong to your company), the endpoint returns 404. See Errors.

Request a withdrawal

POST /withdrawals

Requests a withdrawal by recipientId, aggregating the balance from all wallets in that currency. The withdrawal enters as requested and awaits approval. Returns 201.

recipientId

string

required

ID of the recipient making the withdrawal.

amount

integer

required

Withdrawal amount in cents. Integer, minimum 1.

currency

string

Currency in ISO 4217 format (exactly 3 letters). Optional — when omitted, defaults to BRL.

This endpoint supports idempotency. Send the Idempotency-Key header with a unique key per request to avoid duplicate withdrawals on retry. See Conventions.

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

The returned withdrawal includes walletId (the physical wallet debited — chosen automatically when there is more than one for the currency), amount (gross), fee, and netAmount (amount - fee). The recipient provided in the request is not echoed back in the response body.

Returns 409 when the balance is insufficient, the amount is below the minimum withdrawal threshold, or there is no active wallet for the specified currency. The error body follows the standard format — see Errors.

Cancel a withdrawal

POST /withdrawals/{id}/cancel

Cancels a withdrawal that has not yet been approved (only requested status).

string

required

ID of the withdrawal to cancel. Passed in the URL.

reason

string

Cancellation reason. Optional (minimum 1 character when provided).

Supports idempotency via the Idempotency-Key header.

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

Error statuses:

404 — withdrawal not found.
409 — the withdrawal cannot be cancelled in its current status (already moved past requested).

See the error formats in Errors.

Recipients

Splits

How balance flows into wallets from sales.

Settlement

When and how balance is released for withdrawal.

Webhooks

Receive withdrawal events (withdrawal.*) in your system.

​Endpoints

​Aggregated balance by currency

​Statement summary by period

​Filters (query params)

​Recipient statement

​Pagination (query params)

​Filters (query params)

​Withdrawals (payouts)

​Withdrawal configuration

​List withdrawals

​Retrieve withdrawal by ID

​Request a withdrawal

​Cancel a withdrawal

​See also

Recipients

Splits

Settlement

Webhooks

Endpoints

Aggregated balance by currency

Statement summary by period

Filters (query params)

Recipient statement

Pagination (query params)

Filters (query params)

Withdrawals (payouts)

Withdrawal configuration

List withdrawals

Retrieve withdrawal by ID

Request a withdrawal

Cancel a withdrawal

See also