> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar recebíveis
> Lista paginada dos recebíveis da sua conta, com filtros por recebedor, transação, pagamento, status, tipo, método e período.
`GET /receivables`
Faz parte do recurso [Recebíveis](/pt-BR/receivables) — o conceito, o ciclo de vida e a
tabela de status estão lá.
Retorna os recebíveis da sua conta **do mais próximo de cair ao mais distante** (`expectedAt`
crescente, com `id` como desempate), paginados: `limit` padrão `20`, máximo `100` — confira
`pagination.totalPages` antes de concluir que a lista acabou. Todos os filtros são opcionais e
podem ser combinados. **Sem `status`, vêm todos os status**, inclusive `liquidated` e `cancelled`;
os valores aceitos estão em [Status do recebível](/pt-BR/receivables#status-do-recebível), e as
datas seguem **ISO 8601 com timezone** (veja [Convenções](/pt-BR/convencoes)).
**Filtro com valor inválido é rejeitado, não ignorado.** `?status=pago` responde **400** com
`error.issues[]` apontando o campo e os valores aceitos. O mesmo vale para `type`,
`paymentMethod`, `currency` e para data fora do formato.
O formato do erro está em [Erros](/pt-BR/erros).
**Vários valores no mesmo filtro.** `status`, `type`, `paymentMethod` e `recipientIds` aceitam
uma lista separada por vírgula, e o resultado traz qualquer recebível que case com **um dos**
valores. Ex.: `?status=projected,confirmed&paymentMethod=credit_card`.
**O cronograma de uma venda.** `transactionId` e `paymentId` são match exato:
`?transactionId=txn_...` devolve uma linha por recebedor e por parcela daquela venda, na ordem
em que vão cair — é a forma de saber quando o dinheiro de um pedido chega.
**Sincronização incremental.** Para trazer só o que mudou desde a última execução, combine
`dateField=updatedAt` com `startDate` e ordene por `updatedAt`. O campo muda a cada alteração
do recebível — a confirmação do adquirente, a liquidação, um estorno meses depois da venda —,
o que uma busca por `expectedAt` não traria.
```bash theme={null}
?dateField=updatedAt&startDate=2026-09-16T00:00:00.000Z&sortBy=updatedAt&sortDir=asc
```
Prefira janelas fechadas (`startDate` + `endDate`) a varrer muitas páginas de um período ainda em
aberto: registros alterados durante a varredura mudam de posição e podem escapar da paginação.
**O recebível nasce depois do pagamento, não junto.** Ele é criado instantes após o pagamento ser
confirmado. Quem consulta ao receber o webhook `payment.paid` pode ainda não encontrar nada —
trate a lista vazia como "ainda não projetado" e consulte de novo.
## Exemplo
```bash theme={null}
curl "https://api.sandbox.z2pay.com/v1/receivables?transactionId=txn_b4k7m2p9x3c6v1n8q5w0z7r4t" \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```
```json theme={null}
{
"data": [
{
"id": "rcv_k3m9x2q7v5b8n4c6z1p0w7r2t",
"transactionId": "txn_b4k7m2p9x3c6v1n8q5w0z7r4t",
"paymentId": "pay_c8n2k5x9m4p7v1b3q6w0z2r5t",
"recipientId": "rec_h7d4s9k2m6p1q8w3x5z0v4b7n",
"walletTransactionId": "wtx_m2p8k4x1v7c3b9n5q6w0z2r8t",
"type": "credit",
"flow": "credit",
"status": "liquidated",
"paymentMethod": "credit_card",
"cardBrand": "visa",
"installmentNumber": 1,
"totalInstallments": 3,
"currency": "BRL",
"grossAmount": 10000,
"feeAmount": 350,
"netAmount": 9650,
"anticipationFeeAmount": 0,
"expectedAt": "2026-10-16T03:00:00.000Z",
"paymentAt": "2026-10-16T03:00:00.000Z",
"liquidatedAt": "2026-10-16T12:00:41.000Z",
"createdAt": "2026-09-16T14:02:11.000Z",
"updatedAt": "2026-10-16T12:00:41.000Z"
},
{
"id": "rcv_k3m9x2q7v5b8n4c6z1p0w7r2u",
"transactionId": "txn_b4k7m2p9x3c6v1n8q5w0z7r4t",
"paymentId": "pay_c8n2k5x9m4p7v1b3q6w0z2r5t",
"recipientId": "rec_h7d4s9k2m6p1q8w3x5z0v4b7n",
"walletTransactionId": null,
"type": "credit",
"flow": "credit",
"status": "confirmed",
"paymentMethod": "credit_card",
"cardBrand": "visa",
"installmentNumber": 2,
"totalInstallments": 3,
"currency": "BRL",
"grossAmount": 10000,
"feeAmount": 350,
"netAmount": 9650,
"anticipationFeeAmount": 0,
"expectedAt": "2026-11-15T03:00:00.000Z",
"paymentAt": "2026-11-15T03:00:00.000Z",
"liquidatedAt": null,
"createdAt": "2026-09-16T14:02:11.000Z",
"updatedAt": "2026-09-17T09:00:04.000Z"
},
{
"id": "rcv_k3m9x2q7v5b8n4c6z1p0w7r2v",
"transactionId": "txn_b4k7m2p9x3c6v1n8q5w0z7r4t",
"paymentId": "pay_c8n2k5x9m4p7v1b3q6w0z2r5t",
"recipientId": "rec_h7d4s9k2m6p1q8w3x5z0v4b7n",
"walletTransactionId": null,
"type": "credit",
"flow": "credit",
"status": "confirmed",
"paymentMethod": "credit_card",
"cardBrand": "visa",
"installmentNumber": 3,
"totalInstallments": 3,
"currency": "BRL",
"grossAmount": 10000,
"feeAmount": 350,
"netAmount": 9650,
"anticipationFeeAmount": 0,
"expectedAt": "2026-12-15T03:00:00.000Z",
"paymentAt": "2026-12-15T03:00:00.000Z",
"liquidatedAt": null,
"createdAt": "2026-09-16T14:02:11.000Z",
"updatedAt": "2026-09-17T09:00:04.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 3,
"totalPages": 1
}
}
```
**Uma venda de R\$ 300 em 3x, um mês depois.** A primeira parcela já liquidou: `liquidatedAt`
preenchida e `walletTransactionId` apontando o lançamento correspondente no
[extrato](/pt-BR/wallets/owner-transactions). As outras duas estão `confirmed` — valores
definitivos, falta chegar a data. Um recebível recém-criado vem `projected`, com `feeAmount` `0`
e `netAmount` igual ao bruto, até o adquirente confirmar.
## OpenAPI
````yaml openapi/psp.json GET /receivables
openapi: 3.0.3
info:
title: Z2Pay PSP API
version: 1.0.0
description: API pública do PSP — autenticação via API Key (Credential)
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Cards
description: Cartões salvos de um cliente
- name: Chargebacks
description: Gerenciamento de chargebacks
- name: Customers
description: Gerenciamento de clientes (compradores)
- name: Fees
description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
- name: Receivables
description: >-
Recebíveis: o que cada venda vai depositar na carteira, por recebedor e
parcela, com data prevista e status
- name: Recipients
description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
- name: Refunds
description: Gerenciamento de reembolsos e estornos
- name: Splits
description: Regras de divisão do valor de uma venda entre recebedores
- name: Transactions
description: Gerenciamento de transações e payments
- name: Wallets
description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
- name: Webhooks
description: Configuração, gerenciamento e histórico de entregas de webhooks
- name: Withdrawals
description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
/receivables:
get:
tags:
- Receivables
summary: Listar recebíveis
description: >-
Retorna lista paginada dos recebíveis da conta, ordenada pela data
prevista. Sem filtro de status devolve todos; filtre por recebedor,
transação, pagamento, status, tipo, método e período (startDate/endDate
sobre dateField). Para sincronização incremental use dateField=updatedAt
com sortBy=updatedAt.
operationId: ReceivableController_list
parameters:
- name: page
in: query
required: false
description: 'Página da listagem. Padrão: 1.'
schema:
type: integer
minimum: 1
default: 1
description: 'Página da listagem. Padrão: 1.'
- name: limit
in: query
required: false
description: 'Itens por página. Padrão: 20. Máximo: 100.'
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: 'Itens por página. Padrão: 20. Máximo: 100.'
- name: recipientIds
in: query
required: false
description: >-
IDs de recebedores (rec_). Aceita vários valores separados por
vírgula.
schema:
type: array
items:
type: string
minLength: 1
description: >-
IDs de recebedores (rec_). Aceita vários valores separados por
vírgula.
- name: transactionId
in: query
required: false
description: ID da transação de origem (txn_). Match exato.
schema:
type: string
minLength: 1
nullable: true
description: ID da transação de origem (txn_). Match exato.
- name: paymentId
in: query
required: false
description: ID do pagamento de origem (pay_). Match exato.
schema:
type: string
minLength: 1
nullable: true
description: ID do pagamento de origem (pay_). Match exato.
- name: status
in: query
required: false
description: >-
Status do recebível. Aceita vários valores separados por vírgula.
Sem o filtro, todos os status.
schema:
type: array
items:
type: string
enum:
- projected
- confirmed
- paid
- liquidated
- anticipated
- cancelled
description: >-
Status do recebível. Aceita vários valores separados por vírgula.
Sem o filtro, todos os status.
- name: type
in: query
required: false
description: >-
Natureza do lançamento: credit, refund_reversal e chargeback_refund
somam; refund e chargeback subtraem. Aceita vários valores separados
por vírgula.
schema:
type: array
items:
type: string
enum:
- credit
- refund
- refund_reversal
- chargeback
- chargeback_refund
description: >-
Natureza do lançamento: credit, refund_reversal e
chargeback_refund somam; refund e chargeback subtraem. Aceita
vários valores separados por vírgula.
- name: paymentMethod
in: query
required: false
description: >-
Método de pagamento da venda de origem. Aceita vários valores
separados por vírgula.
schema:
type: array
items:
type: string
enum:
- credit_card
- debit_card
- boleto
- pix
description: >-
Método de pagamento da venda de origem. Aceita vários valores
separados por vírgula.
- name: currency
in: query
required: false
description: Moeda (ISO 4217). Hoje o único valor aceito é 'BRL'.
schema:
type: string
enum:
- BRL
nullable: true
description: Moeda (ISO 4217). Hoje o único valor aceito é 'BRL'.
- name: startDate
in: query
required: false
description: >-
Data inicial, ISO 8601 com timezone, inclusive. Aplica-se ao campo
indicado em dateField.
schema:
type: string
format: date-time
nullable: true
description: >-
Data inicial, ISO 8601 com timezone, inclusive. Aplica-se ao campo
indicado em dateField.
- name: endDate
in: query
required: false
description: >-
Data final, ISO 8601 com timezone, inclusive. Aplica-se ao campo
indicado em dateField.
schema:
type: string
format: date-time
nullable: true
description: >-
Data final, ISO 8601 com timezone, inclusive. Aplica-se ao campo
indicado em dateField.
- name: dateField
in: query
required: false
description: >-
Campo de data ao qual startDate/endDate se aplicam. Padrão:
expectedAt. Use updatedAt para sincronização incremental (o campo
muda a cada alteração do recebível).
schema:
type: string
enum:
- expectedAt
- updatedAt
nullable: true
description: >-
Campo de data ao qual startDate/endDate se aplicam. Padrão:
expectedAt. Use updatedAt para sincronização incremental (o campo
muda a cada alteração do recebível).
- name: sortBy
in: query
required: false
description: 'Campo de ordenação. Padrão: expectedAt.'
schema:
type: string
enum:
- expectedAt
- updatedAt
nullable: true
description: 'Campo de ordenação. Padrão: expectedAt.'
- name: sortDir
in: query
required: false
description: >-
Direção da ordenação. Padrão: asc (do mais próximo ao mais
distante).
schema:
type: string
enum:
- asc
- desc
nullable: true
description: >-
Direção da ordenação. Padrão: asc (do mais próximo ao mais
distante).
responses:
'200':
description: Lista paginada de recebíveis
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: ID do recebível (rcv_).
transactionId:
type: string
nullable: true
description: Transação de origem (txn_).
paymentId:
type: string
description: Pagamento de origem (pay_).
recipientId:
type: string
description: Recebedor desta parcela (rec_).
walletTransactionId:
type: string
nullable: true
description: >-
Lançamento do extrato gerado na liquidação (GET
/wallets/owner/{recipientId}/transactions). null
enquanto não liquidou, ou quando o valor foi pago
fora da carteira.
type:
type: string
enum:
- credit
- refund
- refund_reversal
- chargeback
- chargeback_refund
description: >-
Natureza: credit (venda); refund e chargeback
(débitos); refund_reversal e chargeback_refund
(devolução de um débito).
flow:
type: string
enum:
- credit
- debit
description: >-
credit soma na carteira, debit subtrai. Os valores
são sempre positivos.
status:
type: string
enum:
- projected
- confirmed
- paid
- liquidated
- anticipated
- cancelled
description: >-
projected (previsão) → confirmed (confirmado pelo
adquirente) → paid (pago, liquidando) → liquidated
(na carteira). anticipated = adiantado; cancelled =
não será recebido.
paymentMethod:
type: string
nullable: true
description: credit_card, debit_card, pix ou boleto.
cardBrand:
type: string
nullable: true
description: Bandeira do cartão, quando o adquirente informa.
installmentNumber:
type: integer
description: Número desta parcela.
totalInstallments:
type: integer
description: Total de parcelas da venda.
currency:
type: string
description: Moeda (ISO 4217).
grossAmount:
type: integer
description: Bruto da parcela, em centavos.
feeAmount:
type: integer
description: >-
Taxas descontadas, em centavos. Zero enquanto
projected.
netAmount:
type: integer
description: >-
Líquido, em centavos. Igual ao bruto enquanto
projected.
anticipationFeeAmount:
type: integer
description: >-
Custo da antecipação, em centavos; zero quando não
antecipado. Valor presente = netAmount −
anticipationFeeAmount.
expectedAt:
type: string
format: date-time
description: Data prevista de recebimento.
paymentAt:
type: string
format: date-time
nullable: true
description: >-
Data de pagamento confirmada pelo adquirente; null
até o adquirente confirmar.
liquidatedAt:
type: string
format: date-time
nullable: true
description: Quando o valor caiu na carteira.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: >-
Muda a cada alteração do recebível — base da
sincronização incremental (dateField=updatedAt).
required:
- id
- transactionId
- paymentId
- recipientId
- walletTransactionId
- type
- flow
- status
- paymentMethod
- cardBrand
- installmentNumber
- totalInstallments
- currency
- grossAmount
- feeAmount
- netAmount
- anticipationFeeAmount
- expectedAt
- paymentAt
- liquidatedAt
- createdAt
- updatedAt
description: Lista de registros retornados na página atual.
pagination:
type: object
properties:
page:
type: integer
description: Página atual retornada.
limit:
type: integer
description: Quantidade de itens por página.
total:
type: integer
description: Total de itens que atendem ao filtro.
totalPages:
type: integer
description: Total de páginas disponíveis.
required:
- page
- limit
- total
- totalPages
description: Dados de paginação do resultado.
required:
- data
- pagination
example:
data:
- id: rcv_k3m9x2q7v5b8n4c6z1p0w7r2u
transactionId: txn_b4k7m2p9x3c6v1n8q5w0z7r4t
paymentId: pay_c8n2k5x9m4p7v1b3q6w0z2r5t
recipientId: rec_h7d4s9k2m6p1q8w3x5z0v4b7n
walletTransactionId: null
type: credit
flow: credit
status: confirmed
paymentMethod: credit_card
cardBrand: visa
installmentNumber: 2
totalInstallments: 3
currency: BRL
grossAmount: 10000
feeAmount: 350
netAmount: 9650
anticipationFeeAmount: 0
expectedAt: '2026-11-15T03:00:00.000Z'
paymentAt: '2026-11-15T03:00:00.000Z'
liquidatedAt: null
createdAt: '2026-09-16T14:02:11.000Z'
updatedAt: '2026-09-17T09:00:04.000Z'
pagination:
page: 1
limit: 20
total: 1
totalPages: 1
'400':
description: >-
Filtro inválido: status, tipo, método ou moeda fora dos valores
aceitos, ou data fora do ISO 8601 com timezone
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````