> ## 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 transações
> Lista paginada de transações, com filtros por status, cliente, período e metadados.
`GET /transactions`
Faz parte do recurso [Transações](/pt-BR/transactions) — o conceito, o ciclo de vida e a
tabela de status estão lá.
Retorna uma lista paginada. Todos os filtros são opcionais e podem ser combinados. Os valores
aceitos em `status` são os de [Status da transação](/pt-BR/transactions#status-da-transação),
e as datas seguem **ISO 8601 com timezone** (veja [Convenções](/pt-BR/convencoes)).
**Filtro com valor inválido é rejeitado, não ignorado.** `?status=xpto` responde **400** com
`error.issues[]` apontando o campo e os valores aceitos.
O formato do erro e a lista de códigos estão em [Erros](/pt-BR/erros).
**Vários valores no mesmo filtro.** `status`, `currency`, `paymentMethod` e `recipientIds` aceitam
uma lista separada por vírgula, e o resultado traz qualquer transação que case com **um dos**
valores. Ex.: `?status=paid,refused&paymentMethod=pix,boleto`.
**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 `updatedAt` é atualizado a
cada mudança de estado da transação — inclusive um estorno meses depois da venda, que uma busca por
`createdAt` não traria.
```bash theme={null}
?dateField=updatedAt&startDate=2026-06-24T00: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.
## Exemplo
```bash theme={null}
curl "https://api.sandbox.z2pay.com/v1/transactions?status=paid,partially_paid&sortBy=createdAt&sortDir=desc&limit=20" \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```
```json theme={null}
{
"data": [
{
"id": "txn_ebgsvfsb4151nmbgvj4sek6ol",
"referenceCode": "pedido-2026-0001",
"status": "paid",
"amount": 9990,
"currency": "BRL",
"customerId": "cust_lhsmn6ugmjotm5qvnunrr2hz1",
"createdAt": "2026-06-24T12:00:00.000Z",
"payments": [
{
"id": "pay_kd6z67zbp52rgtg2idms96fhm",
"paymentMethod": "pix",
"status": "paid",
"amount": 9990
}
],
"items": [
{
"id": "item_s4206yea51f6fsiugybgb51sr",
"description": "Plano Pro (mensal)",
"quantity": 1,
"unitValue": 9990,
"amount": 9990
}
]
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"totalPages": 1
}
}
```
**A listagem já traz `payments` e `items`.** Cada item de `data` vem com os pagamentos (com dados
do cartão e os splits, quando houver) e os itens da transação. Para percorrer transações com seus
pagamentos **não é preciso** chamar `GET /transactions/{id}` de novo para cada uma.
Como o payload por transação é grande, prefira `limit` menor quando estiver varrendo muitos
registros.
**Os dados do cliente vêm em duas formas.** A transação carrega o *snapshot* do comprador no
momento da compra — `customerName`, `customerEmail`, `customerDocument`, `customerDocumentType` e
`customerPhone` — que não muda depois, mesmo que o cliente atualize o cadastro. É o que você quer
para conferir uma venda antiga.
Para o cadastro **atual** (incluindo endereço), use o `customerId` em
[`GET /customers/{id}`](/pt-BR/customers/get). O objeto `customer` completo vem em
[`GET /transactions/{id}`](/pt-BR/transactions/get), não na listagem.
## OpenAPI
````yaml openapi/psp.json GET /transactions
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: 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:
/transactions:
get:
tags:
- Transactions
summary: Listar transações
description: Retorna lista paginada de transações da company, com suporte a filtros
operationId: TransactionController_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: currency
in: query
required: false
description: Moeda (ISO 4217). Hoje o único valor aceito é 'BRL'.
schema:
type: array
items:
type: string
enum:
- BRL
description: Moeda (ISO 4217). Hoje o único valor aceito é 'BRL'.
- name: status
in: query
required: false
description: Status da transação. Aceita vários valores separados por vírgula.
schema:
type: array
items:
type: string
description: Status da transação. Aceita vários valores separados por vírgula.
- name: customerName
in: query
required: false
description: Nome do cliente. Busca parcial (contém).
schema:
type: string
nullable: true
description: Nome do cliente. Busca parcial (contém).
- name: customerEmail
in: query
required: false
description: E-mail do cliente. Busca parcial (contém).
schema:
type: string
nullable: true
description: E-mail do cliente. Busca parcial (contém).
- name: customerDocument
in: query
required: false
description: >-
Documento do cliente. Match exato — precisa ser idêntico ao
cadastrado.
schema:
type: string
nullable: true
description: >-
Documento do cliente. Match exato — precisa ser idêntico ao
cadastrado.
- name: referenceCode
in: query
required: false
description: Seu código de referência para a transação. Match exato.
schema:
type: string
nullable: true
description: Seu código de referência para a transação. Match exato.
- name: recipientIds
in: query
required: false
description: >-
IDs de recebedores (rec_) que devem aparecer em algum split da
transação. Aceita vários valores separados por vírgula.
schema:
type: array
items:
type: string
minLength: 1
description: >-
IDs de recebedores (rec_) que devem aparecer em algum split da
transação. Aceita vários valores separados por vírgula.
- name: additionalInfoSearch
in: query
required: false
description: >-
Busca textual dentro de `additionalInfo`. O match é parcial e roda
sobre o JSON inteiro, então casa também o nome da chave, não só o
valor.
schema:
type: string
nullable: true
description: >-
Busca textual dentro de `additionalInfo`. O match é parcial e roda
sobre o JSON inteiro, então casa também o nome da chave, não só o
valor.
- name: startDate
in: query
required: false
description: >-
Data inicial, ISO 8601 com timezone. Aplica-se ao campo indicado em
dateField.
schema:
type: string
format: date-time
nullable: true
description: >-
Data inicial, ISO 8601 com timezone. Aplica-se ao campo indicado
em dateField.
- name: endDate
in: query
required: false
description: >-
Data final, ISO 8601 com timezone. Aplica-se ao campo indicado em
dateField.
schema:
type: string
format: date-time
nullable: true
description: >-
Data final, ISO 8601 com timezone. Aplica-se ao campo indicado em
dateField.
- name: paymentMethod
in: query
required: false
description: >-
Método de pagamento usado na transação. Aceita vários valores
separados por vírgula. `combined` traz as transações com dois ou
mais pagamentos ativos.
schema:
type: array
items:
type: string
enum:
- credit_card
- boleto
- pix
- combined
description: >-
Método de pagamento usado na transação. Aceita vários valores
separados por vírgula. `combined` traz as transações com dois ou
mais pagamentos ativos.
- name: dateField
in: query
required: false
description: >-
Campo de data ao qual startDate/endDate se aplicam. Padrão:
createdAt.
schema:
type: string
enum:
- createdAt
- updatedAt
- paidAt
- refundedAt
- canceledAt
- chargedbackAt
- protestedAt
nullable: true
description: >-
Campo de data ao qual startDate/endDate se aplicam. Padrão:
createdAt.
- name: sortBy
in: query
required: false
description: >-
Campo de ordenação. Padrão: createdAt. Use updatedAt para
sincronização incremental (o campo muda a cada alteração da
transação).
schema:
type: string
enum:
- createdAt
- updatedAt
nullable: true
description: >-
Campo de ordenação. Padrão: createdAt. Use updatedAt para
sincronização incremental (o campo muda a cada alteração da
transação).
- name: sortDir
in: query
required: false
description: 'Direção da ordenação. Padrão: desc.'
schema:
type: string
enum:
- asc
- desc
nullable: true
description: 'Direção da ordenação. Padrão: desc.'
responses:
'200':
description: Lista paginada de transações
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
customerId:
type: string
nullable: true
description: ID do cliente associado à transação.
amount:
type: integer
description: Valor em centavos.
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
paidAmount:
type: integer
description: Valor efetivamente pago, em centavos.
refundedAmount:
type: integer
description: Valor total estornado, em centavos.
status:
type: string
description: >-
Situação da transação, derivada dos pagamentos.
Valores: `pending`, `waiting_payment`,
`partially_paid`, `paid`, `refused`, `failed`,
`canceled`, `waiting_refund`, `partially_refunded`,
`refunded`, `chargeback`, `in_protest`.
parentTransactionId:
type: string
nullable: true
description: >-
ID da transação de origem, quando esta é derivada de
outra.
referenceCode:
type: string
nullable: true
description: >-
Código de referência definido pelo integrador na
criação.
ip:
type: string
nullable: true
description: Endereço IP de origem da transação.
additionalInfo:
type: object
nullable: true
description: Informações adicionais do registro (dados livres).
customerName:
type: string
nullable: true
description: Nome do cliente da transação.
customerEmail:
type: string
nullable: true
description: E-mail do cliente da transação.
customerDocument:
type: string
nullable: true
description: Documento (CPF ou CNPJ) do cliente da transação.
customerDocumentType:
type: string
nullable: true
description: 'Tipo de documento do cliente: cpf ou cnpj.'
customerPhone:
type: string
nullable: true
description: Telefone do cliente da transação.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: >-
Data e hora da última atualização do registro (ISO
8601).
paidAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que o pagamento foi liquidado (ISO
8601).
expiresAt:
type: string
format: date-time
nullable: true
description: Data e hora em que o registro expira (ISO 8601).
canceledAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a transação foi cancelada (ISO
8601).
refundedAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que o estorno foi concluído (ISO
8601).
chargedbackAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a transação sofreu chargeback
(ISO 8601).
protestedAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a transação foi protestada (ISO
8601).
items:
type: array
description: >-
Itens da transação. Vazio quando a transação não tem
itens.
items:
type: object
properties:
id:
type: string
description: ID do item.
transactionId:
type: string
description: Transação a que o item pertence.
code:
type: string
nullable: true
description: Seu código/SKU do item.
description:
type: string
description: Descrição do item.
unitValue:
type: integer
description: Valor unitário, em centavos.
quantity:
type: integer
description: Quantidade.
amount:
type: integer
description: >-
Total da linha, em centavos (`unitValue` ×
`quantity`).
createdAt:
type: string
description: Criação, ISO 8601.
updatedAt:
type: string
description: Última alteração, ISO 8601.
payments:
type: array
description: >-
Pagamentos da transação, com cartão e splits quando
houver.
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
transactionId:
type: string
description: ID da transação relacionada ao registro.
replacedByPaymentId:
type: string
nullable: true
description: >-
ID do pagamento que substituiu este, em caso
de retentativa.
amount:
type: integer
description: Valor em centavos.
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
installments:
type: integer
description: Número de parcelas.
paymentMethod:
type: string
description: >-
Forma de pagamento (ex.: credit_card, pix,
boleto).
cardId:
type: string
nullable: true
description: ID do cartão tokenizado usado no pagamento.
status:
type: string
description: >-
Situação do pagamento. Valores: `pending`,
`waiting_payment`, `paid`, `refused`,
`failed`, `canceled`, `replaced`,
`waiting_refund`, `partially_refunded`,
`refunded`, `chargeback`, `in_protest`.
additionalInfo:
type: object
nullable: true
description: >-
Informações adicionais do registro (dados
livres).
statementDescriptor:
type: string
nullable: true
description: >-
Texto exibido na fatura do cliente (statement
descriptor).
billingAddress:
type: object
nullable: true
description: >-
Endereço de cobrança do cartão, como informado
na criação da transação. Snapshot: preservado
como veio, mesmo que o cadastro do cliente
mude depois.
properties:
street:
type: string
nullable: true
description: Logradouro (rua, avenida).
number:
type: string
nullable: true
description: Número do endereço.
complement:
type: string
nullable: true
description: >-
Complemento do endereço (apartamento,
bloco, sala).
neighborhood:
type: string
nullable: true
description: Bairro.
city:
type: string
nullable: true
description: Cidade.
state:
type: string
nullable: true
description: 'Estado ou UF (ex.: SP).'
country:
type: string
nullable: true
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
postalCode:
type: string
nullable: true
description: CEP / código postal (somente dígitos).
boletoUrl:
type: string
nullable: true
description: URL para visualização e impressão do boleto.
boletoDigitableLine:
type: string
nullable: true
description: Linha digitável do boleto.
boletoBarcode:
type: string
nullable: true
description: Código de barras do boleto.
pixUrl:
type: string
nullable: true
description: URL do QR Code PIX para pagamento.
pixCopyPaste:
type: string
nullable: true
description: >-
Código PIX copia e cola (payload EMV) para
pagamento.
splitConfigId:
type: string
nullable: true
description: >-
ID da configuração de split aplicada ao
pagamento.
originalAmount:
type: integer
nullable: true
description: >-
Valor original do pagamento antes de ajustes,
em centavos.
acquirerReturnCode:
type: string
nullable: true
description: >-
Código de retorno enviado pelo adquirente ao
processar o pagamento.
acquirerReturnMessage:
type: string
nullable: true
description: >-
Mensagem de retorno enviada pelo adquirente ao
processar o pagamento.
retryable:
type: boolean
nullable: true
description: >-
Indica se o pagamento recusado pode ser
retentado.
declineCode:
type: string
nullable: true
description: Código de recusa retornado pelo adquirente.
errorMessage:
type: string
nullable: true
description: Mensagem de erro quando o processamento falha.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: >-
Data e hora da última atualização do registro
(ISO 8601).
paidAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que o pagamento foi liquidado
(ISO 8601).
expiresAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que o registro expira (ISO
8601).
canceledAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a transação foi cancelada
(ISO 8601).
refundedAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que o estorno foi concluído
(ISO 8601).
chargedbackAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a transação sofreu
chargeback (ISO 8601).
protestedAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a transação foi protestada
(ISO 8601).
card:
type: object
nullable: true
description: >-
Dados do cartão usado no pagamento. Ausente
fora de `credit_card`.
properties:
id:
type: string
description: ID do cartão (`crd_`).
brand:
type: string
description: 'Bandeira (ex.: `visa`, `mastercard`).'
firstDigits:
type: string
description: Seis primeiros dígitos.
lastDigits:
type: string
description: Quatro últimos dígitos.
holderName:
type: string
description: Nome impresso no cartão.
expirationMonth:
type: string
description: Mês de validade (`MM`).
expirationYear:
type: string
description: Ano de validade (`YYYY`).
status:
type: string
description: Situação do cartão.
createdAt:
type: string
description: Criação, ISO 8601.
updatedAt:
type: string
description: Última alteração, ISO 8601.
splits:
type: array
description: >-
Divisão do valor deste pagamento entre
recebedores. Vazio quando não há split.
items:
type: object
properties:
id:
type: string
description: ID do split.
paymentId:
type: string
description: Pagamento dividido.
recipientId:
type: string
description: Recebedor (`rec_`).
recipientName:
type: string
nullable: true
description: >-
Nome do recebedor, resolvido no momento
da consulta.
value:
type: integer
description: >-
Valor configurado: percentual (0–100) ou
valor fixo em centavos, conforme
`valueType`.
amount:
type: integer
description: >-
Valor efetivamente destinado ao
recebedor, em centavos.
currency:
type: string
description: Moeda, ISO 4217.
type:
type: string
description: Papel do recebedor na divisão.
typeLabel:
type: string
description: Rótulo legível de `type`.
valueType:
type: string
description: 'Como ler `value`: percentual ou fixo.'
processingFee:
type: boolean
description: >-
Se este recebedor arca com a taxa de
processamento.
liable:
type: boolean
description: >-
Se este recebedor responde por
chargebacks.
createdAt:
type: string
description: Criação, ISO 8601.
updatedAt:
type: string
description: Última alteração, ISO 8601.
customerAddress:
type: object
nullable: true
properties:
street:
type: string
nullable: true
description: Logradouro (rua, avenida).
number:
type: string
nullable: true
description: Número do endereço.
complement:
type: string
nullable: true
description: >-
Complemento do endereço (apartamento, bloco,
sala).
neighborhood:
type: string
nullable: true
description: Bairro.
city:
type: string
nullable: true
description: Cidade.
state:
type: string
nullable: true
description: 'Estado ou UF (ex.: SP).'
postalCode:
type: string
nullable: true
description: CEP / código postal (somente dígitos).
country:
type: string
nullable: true
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
description: >-
Endereço informado nesta compra, congelado no
momento da criação. É este que vale para nota fiscal
e antifraude: editar o cadastro do cliente depois
não o altera. Compare com `customer.address`, que
reflete o cadastro atual.
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.
description: Dados de paginação do resultado.
example:
data:
- id: txn_raqtaj22an9s5dexc1vthopl8
customerId: cust_f7vm6b4j4cckf8gli2b2472ix
amount: 19990
currency: BRL
paidAmount: 19990
refundedAmount: 0
status: paid
parentTransactionId: null
referenceCode: ORDER-2025-00123
ip: 189.45.12.34
additionalInfo:
source: checkout-web
customerName: Maria Silva
customerEmail: maria.silva@example.com
customerDocument: '12345678909'
customerDocumentType: cpf
customerPhone: '+5511987654321'
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:46:10.000Z'
paidAt: '2026-06-24T12:05:00.000Z'
expiresAt: '2026-06-25T12:00:00.000Z'
canceledAt: null
refundedAt: null
chargedbackAt: null
protestedAt: null
items:
- id: item_s4206yea51f6fsiugybgb51sr
transactionId: txn_raqtaj22an9s5dexc1vthopl8
code: PLANO-PRO
description: Plano Pro (mensal)
unitValue: 19990
quantity: 1
amount: 19990
createdAt: '2026-06-24T12:00:00.000Z'
updatedAt: '2026-06-24T12:00:00.000Z'
payments:
- id: pay_kd6z67zbp52rgtg2idms96fhm
transactionId: txn_raqtaj22an9s5dexc1vthopl8
replacedByPaymentId: null
amount: 19990
currency: BRL
installments: 1
paymentMethod: pix
cardId: null
status: paid
additionalInfo: null
statementDescriptor: null
billingAddress: null
boletoUrl: null
boletoDigitableLine: null
boletoBarcode: null
pixUrl: >-
https://pix.z2pay.com/qr/pay_kd6z67zbp52rgtg2idms96fhm/qr.png
pixCopyPaste: >-
00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540519.905802BR5913LOJA
EXEMPLO6009SAO PAULO62070503***6304A1B2
splitConfigId: null
originalAmount: null
acquirerReturnCode: null
acquirerReturnMessage: null
retryable: null
declineCode: null
errorMessage: null
createdAt: '2026-06-24T12:00:00.000Z'
updatedAt: '2026-06-24T12:05:00.000Z'
paidAt: '2026-06-24T12:05:00.000Z'
expiresAt: '2026-06-25T12:00:00.000Z'
canceledAt: null
refundedAt: null
chargedbackAt: null
protestedAt: null
card: null
splits: []
customerAddress:
street: Av. Paulista
number: '1000'
complement: Conj. 101
neighborhood: Bela Vista
city: São Paulo
state: SP
postalCode: '01310100'
country: BR
pagination:
page: 1
limit: 20
total: 1
totalPages: 1
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
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)
````