> ## 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.
# Criar recebedor
> Cadastra quem vai receber repasses na sua conta — ou reaproveita um cadastro que já existe.
`POST /recipients`
Faz parte do recurso [Recebedores](/pt-BR/recipients) — os estados do vínculo, o ciclo de aprovação
e o catálogo de pendências estão lá.
Cria o recebedor e o vincula à sua conta. A resposta traz o cadastro e o **estado do vínculo com a
sua conta** — `status` e `role` descrevem a relação, não a pessoa.
**Criar não é o mesmo que poder receber.** O recebedor nasce em `new` e só vira destino válido de
[split](/pt-BR/splits) quando chega a `active`. Entre uma coisa e outra há documentos a enviar e,
em muitos casos, prova de vida. Ver
[Ciclo de aprovação](/pt-BR/recipients#ciclo-de-aprovação-kyc).
**Quem identifica o recebedor é o documento, não o e-mail.** Se o CPF ou CNPJ já existe na
plataforma, a chamada **vincula o cadastro existente** à sua conta em vez de duplicá-lo — o mesmo
recebedor pode receber de várias contas.
**Repetir a chamada para quem já está vinculado devolve o vínculo como está.** Não há erro nem
vínculo novo: se aquele recebedor já foi aprovado na sua conta, a resposta vem com
`status: "active"`. Uma integração que assuma `new` no `201` erra exatamente no reenvio.
**O e-mail é que gera conflito.** Responde `409` quando o e-mail informado já pertence a **outro
documento** — a mensagem não revela qual, de propósito. Também responde `409` quando o e-mail é de
uma conta de usuário da plataforma. A saída é usar um e-mail do próprio recebedor, não o do
lojista.
**Cadastro incompleto é aceito.** Sem endereço principal ou sem conta bancária, o recebedor nasce
em `new` e fica parado: nada é enviado para análise até o cadastro fechar. É o caminho para quem
coleta os dados aos poucos.
## Exemplo
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/recipients \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-H "Content-Type: application/json" \
-d '{
"name": "Loja do João ME",
"type": "company",
"document": "12345678000190",
"email": "financeiro@lojadojoao.com.br",
"phone": "+5511987654321"
}'
```
```json Resposta 201 theme={null}
{
"id": "rec_v57bi6ruyolouw3cpaq2ofy1k",
"name": "Loja do João ME",
"document": "12345678000190",
"email": "financeiro@lojadojoao.com.br",
"type": "company",
"role": "seller",
"status": "new",
"analysisComplete": false,
"pendencies": [],
"pendenciesSummary": { "open": 0, "blocking": 0, "warning": 0 },
"approvedAt": null,
"refusedAt": null
}
```
O exemplo está abreviado — o playground ao lado mostra o corpo inteiro, com endereço, conta
bancária, sócios e as configurações de antecipação. O identificador do recebedor é o `id`
(`rec_`); é ele que as demais rotas recebem.
## OpenAPI
````yaml openapi/psp.json POST /recipients
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:
post:
tags:
- Recipients
summary: Criar recebedor
description: >-
Cria o recebedor na sua conta, ou vincula um que já existe: quando o
documento já está cadastrado em outra conta, o cadastro é reaproveitado
em vez de duplicado. Responde 409 se o e-mail pertencer a outro
documento.
operationId: RecipientController_create
parameters:
- name: Idempotency-Key
in: header
required: false
description: Chave única para idempotência
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 2
description: Nome do recebedor.
email:
type: string
format: email
description: E-mail do recebedor.
phone:
type: string
nullable: true
description: 'Telefone do recebedor (formato E.164, ex.: +5511987654321).'
document:
type: string
minLength: 11
description: Documento do recebedor (CPF ou CNPJ, somente dígitos).
type:
type: string
enum:
- individual
- company
description: >-
Tipo do recebedor: individual (pessoa física) ou company
(pessoa jurídica).
companyType:
type: string
nullable: true
description: Tipo de empresa do recebedor (pessoa jurídica).
companyLegalName:
type: string
nullable: true
description: Razão social da empresa.
companyFoundingDate:
type: string
nullable: true
description: Data de fundação da empresa.
annualRevenue:
type: integer
minimum: 0
maximum: 100000000000000
description: Faturamento anual da empresa, em centavos.
corporationType:
type: string
nullable: true
description: 'Natureza jurídica da empresa (ex.: LTDA, EIRELI, SA).'
birthDate:
type: string
nullable: true
description: Data de nascimento do recebedor (pessoa física).
motherName:
type: string
nullable: true
description: Nome da mãe do recebedor (pessoa física).
profession:
type: string
nullable: true
description: Profissão do recebedor (pessoa física).
monthlyIncome:
type: integer
minimum: 0
maximum: 100000000000000
nullable: true
description: Renda mensal do recebedor, em centavos.
legalRepresentativeInfo:
type: object
properties:
name:
type: string
description: Nome do representante legal.
email:
type: string
format: email
description: E-mail do representante legal.
document:
type: string
description: CPF do representante legal (somente dígitos).
motherName:
type: string
nullable: true
description: Nome da mãe do representante legal.
birthdate:
type: string
nullable: true
description: Data de nascimento do representante legal.
monthlyIncome:
type: integer
minimum: 0
maximum: 100000000000000
description: Renda mensal do representante legal.
profession:
type: string
nullable: true
description: Profissão do representante legal.
phone:
type: string
nullable: true
description: Telefone do representante legal.
selfDeclaredRepresentative:
type: boolean
description: >-
Indica se a pessoa se autodeclara como representante
legal.
required:
- name
- document
nullable: true
description: Dados do representante legal (recebedor pessoa jurídica).
pixKeyType:
type: string
nullable: true
description: >-
Tipo da chave Pix do recebedor (ex.: cpf, cnpj, email,
phone, random).
pixKey:
type: string
nullable: true
description: Chave Pix do recebedor para recebimentos.
website:
type: string
nullable: true
description: Site do recebedor.
address:
type: object
properties:
address:
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
maxLength: 2
nullable: true
description: 'Estado ou UF (ex.: SP).'
postalCode:
type: string
nullable: true
description: CEP / código postal (somente dígitos).
referencePoint:
type: string
nullable: true
description: Ponto de referência do endereço.
description: Endereço do recebedor.
bankAccount:
type: object
properties:
bankHolderName:
type: string
minLength: 2
description: Nome do titular da conta bancária.
bankHolderDocument:
type: string
minLength: 11
description: >-
Documento do titular da conta (CPF ou CNPJ, somente
dígitos).
bankHolderType:
type: string
nullable: true
description: >-
Tipo do titular da conta: individual (pessoa física) ou
company (pessoa jurídica).
bankCode:
type: string
minLength: 1
description: 'Código do banco (COMPE, ex.: 341).'
bankName:
type: string
nullable: true
description: Nome do banco.
bankAgency:
type: string
minLength: 1
description: Número da agência bancária.
bankAccount:
type: string
minLength: 1
description: Número da conta bancária.
bankAccountDigit:
type: string
nullable: true
description: Dígito verificador da conta.
bankAccountType:
type: string
nullable: true
description: Tipo da conta bancária (corrente ou poupança).
required:
- bankHolderName
- bankHolderDocument
- bankCode
- bankAgency
- bankAccount
description: Dados bancários do recebedor para recebimentos e saques.
files:
type: object
properties:
identificationDocument:
type: string
description: Documento de identificação (RG ou CNH) do recebedor.
selfie:
type: string
description: Selfie do titular para verificação de identidade.
socialContract:
type: string
description: Contrato social da empresa (recebedor pessoa jurídica).
description: Documentos para verificação (KYC) do recebedor.
required:
- name
- email
- document
- type
- monthlyIncome
responses:
'201':
description: Recebedor criado
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.
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: null
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: null
motherName: null
profession: null
monthlyIncome: null
legalRepresentativeInfo: null
pixKeyType: null
pixKey: null
website: null
mainAddress: null
defaultBankAccount: null
role: seller
status: new
splitValue: null
splitType: null
pixAntecipationDays: null
bankSlipAntecipationDays: null
creditCardAntecipationDays: null
approvedAt: null
refusedAt: null
analysisComplete: false
pendencies: []
pendenciesSummary:
open: 0
blocking: 0
warning: 0
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:30.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
'409':
description: E-mail já pertence a outro documento ou a uma conta de usuário
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: A request with this idempotency key is already being processed
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````