> ## 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.
# Recebedores
> Cadastre e gerencie recebedores que recebem repasses via split na Z2Pay.
Recebedores são os **sellers/merchants** que recebem repasses das suas vendas.
Você cadastra um recebedor, ele é vinculado à sua company com um papel (role) e um status,
e a partir daí pode ser usado como destino em um [split de pagamento](/pt-BR/splits).
Um recebedor global (CPF/CNPJ único na plataforma) é vinculado à sua company por um *link*.
A resposta dos endpoints combina os dados do recebedor (nome, documento, conta bancária) com
os dados do link (`status`, `role`, configuração de split).
Todas as requisições usam o header `x-api-key`. Veja [Autenticação](/pt-BR/autenticacao).
A base URL de sandbox é `https://api.sandbox.z2pay.com/v1`.
***
## Endpoints
| Método | Rota | Descrição |
| -------- | -------------------------- | ---------------------------------------------- |
| `GET` | `/recipients` | Lista paginada de recebedores da company |
| `GET` | `/recipients/owner` | Retorna o recebedor com role `owner` |
| `GET` | `/recipients/:id` | Busca um recebedor por ID |
| `POST` | `/recipients` | Cria ou vincula um recebedor à company |
| `PATCH` | `/recipients/:id` | Atualiza dados de um recebedor |
| `POST` | `/recipients/:id/kyc-link` | Gera link KYC para o recebedor completar dados |
| `DELETE` | `/recipients/:id` | Desvincula o recebedor da company |
***
## Status do vínculo
Quem determina o status é a **análise do recebedor** (KYC), não você: criar ou atualizar não
aprova, e o resultado chega por [webhook](/pt-BR/webhooks).
| Status | O que significa | Quando acontece |
| ------------------- | --------------------- | ------------------------------------------------------------------------------ |
| `new` | Cadastro incompleto | O recebedor foi criado sem endereço principal ou sem conta bancária |
| `pending` | Em análise | O cadastro completo foi enviado para análise |
| `awaiting_liveness` | Falta a prova de vida | A análise pediu validação facial — gere o link de KYC e encaminhe ao recebedor |
| `active` | Apto a receber | A análise aprovou; já pode ser destino de [split](/pt-BR/splits) |
| `refused` | Recusado | A análise reprovou; `pendencies` diz o motivo |
**Recebedor owner** é o que representa a sua própria conta, com `role: "owner"` — use
`GET /recipients/owner` para descobrir o ID dele sem precisar guardá-lo. Os demais nascem
com `role: "seller"`.
***
## Ciclo de aprovação (KYC)
Criar ou atualizar um recebedor **não** o aprova na hora. A aprovação passa por uma análise
(KYC) e o resultado é **assíncrono**: você acompanha pelo campo `status` do recebedor e,
principalmente, pelos [webhooks](/pt-BR/webhooks).
O campo `status` do recebedor reflete o estado do vínculo: `new` → `pending` → `active`
(aprovado) ou `refused` (recusado). Consulte-o a qualquer momento com
[`GET /recipients/:id`](#buscar-recebedor-por-id).
A análise funciona em **rodadas**: enquanto a rodada está aberta (`analysisComplete: false`),
nada é avisado — a Z2Pay aguarda a análise inteira terminar e dispara **um** webhook com o
resultado consolidado, em vez de uma rajada de avisos parciais:
| Evento | Significado |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `recipient.approved` | Recebedor aprovado — `status` passa a `active` e ele já pode receber repasses em [splits](/pt-BR/splits). |
| `recipient.refused` | Recebedor recusado — `status` passa a `refused`. As `pendencies` do payload dizem o motivo. |
| `recipient.pendency_updated` | A rodada terminou sem mudar o status final, mas surgiram pendências novas — algo precisa ser corrigido. |
O payload desses eventos é o recebedor completo, no mesmo formato de
[`GET /recipients/:id`](/pt-BR/recipients/get) — incluindo `analysisComplete`, `pendencies` e
`pendenciesSummary`.
Use [`POST /recipients`](#criar-recebedor) com os dados e, se possível, conta bancária.
O vínculo nasce como `new` ou `pending`.
Gere o link com [`POST /recipients/:id/kyc-link`](#gerar-link-kyc) e encaminhe a `kycUrl`
ao recebedor para que ele complete dados e envie documentos.
Aguarde o webhook `recipient.approved`, `recipient.refused` ou
`recipient.pendency_updated`. Quando `status` for `active`, o recebedor está apto a
receber repasses.
Leia `pendencies` (o campo `action` de cada uma diz o que fazer), corrija via
[`PATCH /recipients/:id`](#atualizar-recebedor) ou por um novo link KYC, e aguarde a
próxima rodada de análise.
Configure e assine os eventos `recipient.approved`, `recipient.refused` e
`recipient.pendency_updated` em [Webhooks](/pt-BR/webhooks). Enquanto não chegar o
`recipient.approved`, evite usar o recebedor como destino de split.
***
## Por que meu recebedor foi recusado?
Quando a análise encontra um problema, ele aparece em `pendencies` — tanto na resposta de
[`GET /recipients/:id`](/pt-BR/recipients/get) quanto no payload dos webhooks. Cada
pendência tem esta forma:
```json theme={null}
{
"code": "document_illegible",
"field": "documents.identification",
"severity": "blocking",
"status": "open",
"message": "O documento enviado está ilegível.",
"action": "Reenvie uma foto nítida, colorida e sem cortes do documento.",
"createdAt": "2026-08-01T14:20:00.000Z",
"updatedAt": "2026-08-02T09:10:00.000Z"
}
```
| Campo | O que traz |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `code` | Código **estável** da pendência (catálogo abaixo). É o contrato para automação — ramifique por ele, nunca pelo texto |
| `field` | Campo do cadastro afetado (`document`, `bankAccount`, `documents.selfie`…). Vazio quando a pendência não é de um campo específico |
| `severity` | `blocking` **impede a aprovação** enquanto estiver aberta; `warning` é um dado a corrigir que não trava |
| `status` | `open` ou `resolved` — a resolvida só aparece com `includeResolved=true` |
| `message` | O que está pendente, em texto humano, no idioma da requisição. **Pode mudar de redação** |
| `action` | O que fazer para resolver. Também é texto humano traduzido |
Para exibir as pendências ao seu seller, basta repassar `message` e `action` — eles já vêm
prontos e traduzidos. Para lógica no seu sistema (ex.: reabrir o formulário de conta
bancária), use `code` e `field`.
### Catálogo de códigos
O `code` é sempre um destes valores. A severidade indicada é a padrão — em casos específicos
a análise pode escalar uma `warning` para `blocking`.
#### Documento do titular (CPF/CNPJ)
| Código | Campo | Severidade | O que significa |
| ------------------------- | ---------- | ---------- | ----------------------------------------------- |
| `document_number_invalid` | `document` | blocking | O número do CPF/CNPJ é inválido |
| `document_mismatch` | `document` | blocking | O documento não confere com os dados do titular |
#### Documentos enviados (fotos/arquivos)
| Código | Campo | Severidade | O que significa |
| --------------------------------- | -------------------------- | ---------- | ------------------------------------------------------------- |
| `identification_document_missing` | `documents.identification` | blocking | Documento de identificação (RG/CNH) não enviado ou incompleto |
| `document_illegible` | `documents.identification` | blocking | Documento enviado está ilegível |
| `selfie_missing` | `documents.selfie` | blocking | Selfie do titular não enviada |
| `selfie_invalid` | `documents.selfie` | blocking | Selfie enviada não foi aceita |
| `liveness_required` | `documents.selfie` | blocking | Falta concluir a prova de vida (validação facial) |
| `address_proof_missing` | `documents.addressProof` | blocking | Comprovante de endereço não enviado |
| `social_contract_missing` | `documents.socialContract` | blocking | Contrato social da empresa não enviado |
| `additional_documents_required` | `documents` | blocking | A análise pediu documentos complementares |
#### Dados cadastrais
| Código | Campo | Severidade | O que significa |
| ------------------------------ | ------------------ | ---------- | ----------------------------------------- |
| `name_mismatch` | `name` | blocking | Nome não confere com o do documento |
| `birthdate_invalid` | `birthdate` | blocking | Data de nascimento inválida ou divergente |
| `mother_name_missing` | `motherName` | blocking | Nome da mãe não informado |
| `address_invalid` | `address` | blocking | Endereço incompleto ou inválido |
| `phone_invalid` | `phone` | warning | Telefone inválido |
| `email_invalid` | `email` | warning | E-mail inválido |
| `monthly_income_invalid` | `monthlyIncome` | blocking | Renda/faturamento mensal inválido |
| `legal_representative_missing` | `managingPartners` | blocking | Dados do representante legal incompletos |
#### Conta bancária
| Código | Campo | Severidade | O que significa |
| ------------------------------ | ---------------------------- | ---------- | ----------------------------------------------------------- |
| `bank_account_invalid` | `bankAccount` | blocking | Dados bancários inválidos (banco, agência, conta ou dígito) |
| `bank_account_holder_mismatch` | `bankAccount.holderDocument` | blocking | Titular da conta bancária não é o mesmo do cadastro |
#### Sem detalhe da análise
| Código | Campo | Severidade | O que significa |
| ---------------------- | ----- | ---------- | ------------------------------------------------------------------------------------------------------- |
| `under_review` | — | warning | Cadastro em análise — nenhuma ação necessária, aguarde |
| `rejected_by_acquirer` | — | blocking | O cadastro não foi aprovado na análise, sem detalhamento por campo. Revise dados e documentos e reenvie |
| `unknown` | — | blocking | Há uma pendência não classificada — contate o suporte |
### Exemplo: recebedor recusado
```json theme={null}
{
"id": "rec_v57bi6ruyolouw3cpaq2ofy1k",
"name": "Loja do João ME",
"document": "12345678000190",
"status": "refused",
"analysisComplete": true,
"refusedAt": "2026-08-02T09:10:00.000Z",
"pendencies": [
{
"code": "bank_account_holder_mismatch",
"field": "bankAccount.holderDocument",
"severity": "blocking",
"status": "open",
"message": "O titular da conta bancária não confere com o do cadastro.",
"action": "Informe uma conta bancária no mesmo CPF/CNPJ do cadastro.",
"createdAt": "2026-08-01T14:20:00.000Z",
"updatedAt": "2026-08-02T09:10:00.000Z"
}
],
"pendenciesSummary": { "open": 1, "blocking": 1, "warning": 0 }
}
```
Neste exemplo, o caminho é claro: atualizar a conta bancária do recebedor
([`PATCH /recipients/:id`](#atualizar-recebedor)) com uma conta no mesmo CPF/CNPJ e aguardar a
nova rodada de análise.
Quer testar a recusa sem depender de uma análise real? No sandbox existem
[documentos de teste](/pt-BR/sandbox/documentos) que disparam cada cenário de forma
determinística — igual aos cartões de teste.
***
## Veja também
Use recebedores como destino de repasse em pagamentos.
Como e quando os recebedores recebem os valores.
Gestão de clientes pagadores.
Idempotência, paginação e formatos.