> ## 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 recebedor por ID
> Retorna um recebedor com o estado da análise e as pendências que impedem a aprovação.
`GET /recipients/:id`
Faz parte do recurso [Recebedores](/pt-BR/recipients) — os papéis, o ciclo de aprovação e o
catálogo de pendências estão lá.
Retorna `404` se o recebedor não estiver vinculado à sua company, mesmo que ele exista na
plataforma para outra conta.
**É aqui que se descobre por que um recebedor não foi aprovado.** Além do cadastro, a resposta
traz três campos sobre a análise:
* **`analysisComplete`** — `false` enquanto há rodada em andamento. Enquanto for `false`, o
`status` e as `pendencies` ainda podem mudar.
* **`pendencies`** — o que está errado, item a item, com `code`, `severity` e a `action` que
resolve. O significado de cada `code` está em
[Por que meu recebedor foi recusado?](/pt-BR/recipients#por-que-meu-recebedor-foi-recusado).
* **`pendenciesSummary`** — a contagem `{ open, blocking, warning }`. Se `blocking` for maior
que zero, há algo impedindo a aprovação.
**Por padrão você vê só as pendências abertas.** Com `?includeResolved=true`, a resposta inclui
também o histórico já resolvido (itens com `status: "resolved"`) — útil para auditar o que o
recebedor já corrigiu, e ruído para quem só quer saber o que falta.
**Trate a pendência pelo `code`, nunca pelo texto.** `message` e `action` são escritos para
quem lê e mudam de redação; `code` e `field` são o contrato para automação.
## OpenAPI
````yaml openapi/psp.json GET /recipients/{id}
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:
/recipients/{id}:
get:
tags:
- Recipients
summary: Buscar recebedor por ID
description: >-
Inclui `analysisComplete`, `pendencies` e `pendenciesSummary`. Por
padrão só as pendências abertas; `?includeResolved=true` traz também o
histórico resolvido.
operationId: RecipientController_getById
parameters:
- name: includeResolved
in: query
required: false
description: >-
Por padrão, `pendencies` traz só as pendências abertas. Com `true`,
inclui também o histórico resolvido (`status: resolved`).
schema:
type: string
enum:
- 'true'
- 'false'
description: >-
Com `true`, a resposta traz também as pendências já resolvidas — o
histórico. Omitido, só as abertas.
- name: id
in: path
required: true
description: ID do recebedor
schema:
type: string
responses:
'200':
description: Dados do recebedor
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Identificador único do registro.
accountName:
type: string
nullable: true
description: Nome da conta do recebedor.
name:
type: string
description: Nome do registro.
email:
type: string
description: E-mail de contato.
phone:
type: string
nullable: true
description: Telefone de contato.
document:
type: string
description: Documento (CPF ou CNPJ) do titular.
type:
type: string
description: >-
Tipo do recebedor: `individual` (pessoa física) ou
`company` (pessoa jurídica).
companyType:
type: string
nullable: true
description: Tipo ou natureza jurídica da empresa.
companyLegalName:
type: string
nullable: true
description: Razão social da empresa.
companyFoundingDate:
type: string
format: date-time
nullable: true
description: Data de fundação da empresa (ISO 8601).
annualRevenue:
type: integer
nullable: true
description: Faturamento anual do recebedor, em centavos.
corporationType:
type: string
nullable: true
description: Tipo societário da empresa.
birthDate:
type: string
format: date-time
nullable: true
description: Data de nascimento do recebedor (ISO 8601).
motherName:
type: string
nullable: true
description: Nome da mãe do recebedor.
profession:
type: string
nullable: true
description: Profissão do recebedor.
monthlyIncome:
type: integer
nullable: true
description: Renda mensal do recebedor, em centavos.
legalRepresentativeInfo:
type: object
nullable: true
description: Dados do representante legal da empresa.
pixKeyType:
type: string
nullable: true
description: 'Tipo da chave PIX (ex.: email, cpf, cnpj, phone, random).'
pixKey:
type: string
nullable: true
description: Chave PIX do recebedor.
website:
type: string
nullable: true
description: Site do recebedor.
mainAddress:
type: object
nullable: true
description: Endereço principal do recebedor.
defaultBankAccount:
type: object
nullable: true
description: Conta bancária padrão do recebedor.
documents:
type: array
items:
type: object
nullable: true
description: Documentos enviados para verificação (KYC) do recebedor.
role:
type: string
description: 'Papel do recebedor no split (ex.: seller).'
status:
type: string
description: >-
Situação da conta bancária. Valores: `active`, `inactive`,
`pending`.
splitValue:
type: number
nullable: true
description: >-
Valor do split do recebedor (percentual ou fixo, conforme
splitType).
splitType:
type: string
nullable: true
description: >-
Tipo do valor de split do recebedor (ex.: percentage,
fixed).
pixAntecipationDays:
type: integer
nullable: true
description: Prazo de antecipação para PIX, em dias.
bankSlipAntecipationDays:
type: integer
nullable: true
description: Prazo de antecipação para boleto, em dias.
creditCardAntecipationDays:
type: integer
nullable: true
description: Prazo de antecipação para cartão de crédito, em dias.
approvedAt:
type: string
format: date-time
nullable: true
description: Data e hora em que o recebedor foi aprovado (ISO 8601).
refusedAt:
type: string
format: date-time
nullable: true
description: Data e hora em que o recebedor foi recusado (ISO 8601).
analysisComplete:
type: boolean
description: >-
Indica se a análise cadastral terminou. `false` enquanto
houver rodada de análise aberta para este recebedor na sua
conta.
pendencies:
type: array
items:
type: object
description: >-
Pendências apontadas pela análise. Cada item traz `code`
(estável, para automação), `field`, `severity` (`blocking`
ou `warning`), `status` (`open` ou `resolved`), `message`
e `action` (texto traduzido) e as datas do grupo.
pendenciesSummary:
type: object
description: >-
Contagem das pendências abertas: `open` (total),
`blocking` e `warning`.
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).
example:
id: rec_gk1o75xv3ioi4eoqosorz9s62
accountName: Loja do Joao
name: Joao da Silva
email: joao.silva@example.com
phone: '+5511987654321'
document: '12345678901'
type: individual
companyType: null
companyLegalName: null
companyFoundingDate: null
annualRevenue: null
corporationType: null
birthDate: '1990-04-12T00:00:00.000Z'
motherName: Maria da Silva
profession: Comerciante
monthlyIncome: 850000
legalRepresentativeInfo: null
pixKeyType: email
pixKey: joao.silva@example.com
website: https://lojadojoao.com.br
mainAddress:
id: radr_n5t8wqz2mxk9rpf4hc7ydv3bj
recipientId: rec_gk1o75xv3ioi4eoqosorz9s62
address: Rua das Flores
number: '123'
complement: Apto 45
neighborhood: Centro
city: Sao Paulo
state: SP
postalCode: '01001000'
referencePoint: null
isMain: true
isActive: true
defaultBankAccount:
id: rba_bg9eddocogegc2pbjyexzd104
recipientId: rec_gk1o75xv3ioi4eoqosorz9s62
status: active
bankHolderName: Joao da Silva
bankHolderDocument: '12345678901'
bankHolderType: individual
bankCode: '341'
bankName: Itau Unibanco
bankAgency: '1234'
bankAccount: '567890'
bankAccountDigit: '1'
bankAccountType: checking
documents: []
role: seller
status: active
splitValue: 10
splitType: percentage
pixAntecipationDays: null
bankSlipAntecipationDays: null
creditCardAntecipationDays: null
approvedAt: '2025-06-20T14:30:00.000Z'
refusedAt: null
analysisComplete: true
pendencies: []
pendenciesSummary:
open: 0
blocking: 0
warning: 0
createdAt: '2025-06-18T09:15:00.000Z'
updatedAt: '2025-06-20T14:30:00.000Z'
'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
'404':
description: Recebedor não encontrado
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: Recipient not found
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````