> ## 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.
# Buscar pagamento por ID
> Retorna os dados de um pagamento específico.
`GET /transactions/:transactionId/payments/:paymentId`
Faz parte do recurso [Pagamentos](/pt-BR/payments) — o objeto e os status estão lá.
**Os dois IDs precisam combinar.** O pagamento tem de pertencer à transação informada no caminho;
caso contrário a resposta é `404`, mesmo que ambos existam na sua conta.
Para boleto, use `boletoUrl`, `boletoDigitableLine` e `boletoBarcode`. Para PIX, use `pixUrl` (QR Code) e `pixCopyPaste` (copia-e-cola). Esses campos só ficam preenchidos depois que o pagamento é processado pelo gateway.
**Este endpoint alcança tentativas que a transação esconde.** `GET /transactions/:id` omite os
pagamentos em `replaced`; aqui eles aparecem. É para isso que ele existe — siga o
`replacedByPaymentId` do pagamento novo para chegar à tentativa anterior.
**Em compensação, ele traz menos detalhe do cartão.** Os pagamentos embutidos em
[`GET /transactions/:id`](/pt-BR/transactions/get) vêm com o objeto `card` (bandeira, últimos
quatro dígitos) e com `splits` enriquecidos; aqui não. Se você precisa desses dados, busque pela
transação.
## OpenAPI
````yaml openapi/psp.json GET /transactions/{transactionId}/payments/{paymentId}
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/{transactionId}/payments/{paymentId}:
get:
tags:
- Transactions
summary: Buscar payment por ID
description: Retorna os dados de um payment específico
operationId: PaymentController_getById
parameters:
- name: paymentId
in: path
required: true
description: ID do payment
schema:
type: string
- name: transactionId
in: path
required: true
description: ID da transação
schema:
type: string
responses:
'200':
description: Dados do payment
content:
application/json:
schema:
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).
example:
id: pay_uw2uc9v7log0i8t091r8jojk1
transactionId: txn_raqtaj22an9s5dexc1vthopl8
replacedByPaymentId: null
amount: 19990
currency: BRL
installments: 1
paymentMethod: pix
cardId: null
status: waiting_payment
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: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:31.000Z'
paidAt: null
expiresAt: '2025-06-30T13:45:30.000Z'
canceledAt: null
refundedAt: null
chargedbackAt: null
protestedAt: null
'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
'404':
description: Payment não encontrado nesta transaçã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.
example:
error:
code: NOT_FOUND
message: Payment not found
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````