Recebedores

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. 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. 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.

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
`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. 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. 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.
`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 — incluindo analysisComplete, pendencies e pendenciesSummary.

Criar o recebedor

Use POST /recipients com os dados e, se possível, conta bancária. O vínculo nasce como new ou pending.

Enviar para KYC

Gere o link com POST /recipients/:id/kyc-link e encaminhe a kycUrl ao recebedor para que ele complete dados e envie documentos.

Aguardar o resultado

Aguarde o webhook recipient.approved, recipient.refused ou recipient.pendency_updated. Quando status for active, o recebedor está apto a receber repasses.

Se houver pendências, corrija e reenvie

Leia pendencies (o campo action de cada uma diz o que fazer), corrija via PATCH /recipients/:id 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. 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 quanto no payload dos webhooks. Cada pendência tem esta forma:

{
  "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

{
  "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) 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 que disparam cada cenário de forma determinística — igual aos cartões de teste.

Veja também

Splits

Use recebedores como destino de repasse em pagamentos.

Liquidação

Como e quando os recebedores recebem os valores.

Clientes

Gestão de clientes pagadores.

Convenções

Idempotência, paginação e formatos.

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Endpoints

Status do vínculo

Ciclo de aprovação (KYC)

Por que meu recebedor foi recusado?

Catálogo de códigos

Documento do titular (CPF/CNPJ)

Documentos enviados (fotos/arquivos)

Dados cadastrais

Conta bancária

Sem detalhe da análise

Exemplo: recebedor recusado

Veja também

Splits

Liquidação

Clientes

Convenções

​Endpoints

​Status do vínculo

​Ciclo de aprovação (KYC)

​Por que meu recebedor foi recusado?

​Catálogo de códigos

​Documento do titular (CPF/CNPJ)

​Documentos enviados (fotos/arquivos)

​Dados cadastrais

​Conta bancária

​Sem detalhe da análise

​Exemplo: recebedor recusado

​Veja também

Splits

Liquidação

Clientes

Convenções

Endpoints

Status do vínculo

Ciclo de aprovação (KYC)

Por que meu recebedor foi recusado?

Catálogo de códigos

Documento do titular (CPF/CNPJ)

Documentos enviados (fotos/arquivos)

Dados cadastrais

Conta bancária

Sem detalhe da análise

Exemplo: recebedor recusado

Veja também