Recipients (Recebedores) - Z2Pay Developers

Recebedores (recipients) são os sellers/merchants que recebem repasses das suas vendas. Você cadastra um recipient, 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 recipient global (CPF/CNPJ único na plataforma) é vinculado à sua company por um link. A resposta dos endpoints combina os dados do recipient (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.

Conceitos

Role (papel)

seller (padrão ao criar via API), owner (recebedor principal da company) ou platform (interno). Há no máximo 1 owner por company.

Status do vínculo

new, pending, active, refused ou inactive. Um recipient precisa estar apto para receber repasses antes de ser usado em split.

Recipient owner é o recebedor principal vinculado à sua company com role: "owner". Use GET /recipients/owner para descobrir quem é o owner sem precisar saber o ID dele.

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
`PUT`	`/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

Listar recebedores

GET /recipients

Retorna a lista paginada de recebedores vinculados à sua company. Aceita filtros opcionais por email ou document. Apenas recebedores do tipo merchant aparecem nesta listagem.

Parâmetros de query

page

integer

Página atual (paginação).

limit

integer

Quantidade de itens por página.

string

Filtra por e-mail exato do recebedor. Deve ser um e-mail válido.

document

string

Filtra por documento (CPF/CNPJ). Mínimo de 11 caracteres.

Exemplo

curl https://api.sandbox.z2pay.com/recipients?limit=10 \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "rec_8x2k9d1p4q",
      "name": "Loja do João ME",
      "email": "contato@lojadojoao.com.br",
      "document": "12345678000190",
      "type": "company",
      "phone": "+5511999998888",
      "status": "active",
      "role": "seller",
      "companyId": "comp_a1b2c3d4e5",
      "defaultBankAccount": {
        "id": "rba_3k9d8f2j1",
        "bankCode": "341",
        "bankName": "Itaú",
        "bankAgency": "1234",
        "bankAccount": "56789",
        "bankAccountDigit": "0",
        "bankHolderName": "Loja do João ME",
        "bankHolderDocument": "12345678000190"
      },
      "createdAt": "2026-06-01T13:00:00.000Z",
      "updatedAt": "2026-06-10T09:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}

A combinação de filtros é restritiva: se email e document forem informados e apontarem para recebedores diferentes, a lista volta vazia.

Buscar recebedor owner

GET /recipients/owner

Retorna o recebedor vinculado à sua company com role: "owner". Se a company não tiver um owner definido, a resposta é null.

curl https://api.sandbox.z2pay.com/recipients/owner \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "id": "rec_owner1a2b3c",
  "name": "Minha Empresa LTDA",
  "email": "financeiro@minhaempresa.com.br",
  "document": "98765432000110",
  "type": "company",
  "status": "active",
  "role": "owner",
  "companyId": "comp_a1b2c3d4e5",
  "splitValue": null,
  "splitType": null,
  "createdAt": "2026-05-01T10:00:00.000Z",
  "updatedAt": "2026-05-01T10:00:00.000Z"
}

Quando não há owner, o corpo da resposta é literalmente null (status 200). Trate esse caso no seu código antes de acessar campos.

Buscar recebedor por ID

GET /recipients/:id

string

obrigatório

ID do recebedor (prefixo rec_).

curl https://api.sandbox.z2pay.com/recipients/rec_8x2k9d1p4q \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "id": "rec_8x2k9d1p4q",
  "name": "Loja do João ME",
  "email": "contato@lojadojoao.com.br",
  "document": "12345678000190",
  "type": "company",
  "status": "active",
  "role": "seller",
  "companyId": "comp_a1b2c3d4e5",
  "splitValue": 10,
  "splitType": "percentage",
  "createdAt": "2026-06-01T13:00:00.000Z",
  "updatedAt": "2026-06-10T09:30:00.000Z"
}

Retorna 404 se o recebedor não estiver vinculado à sua company. Veja Erros.

Criar recebedor

POST /recipients

Cria um recebedor (cadastro global por CPF/CNPJ) e o vincula à sua company com role: "seller". Se já existir um recebedor merchant com o mesmo documento ou e-mail, ele é reutilizado e seus dados são atualizados com o que você enviar. Retorna status 201. Suporta idempotência via header Idempotency-Key — veja Convenções.

O status inicial do vínculo depende dos dados enviados: com endereço principal e conta bancária preenchidos, o vínculo nasce como pending; caso contrário, nasce como new.

Campos do corpo

name

string

obrigatório

Nome do recebedor. Mínimo de 2 caracteres.

string

obrigatório

E-mail válido do recebedor.

document

string

obrigatório

CPF ou CNPJ. Mínimo de 11 caracteres.

type

string

obrigatório

Tipo do recebedor. Valores: individual ou company.

phone

string

Telefone do recebedor.

kind

string

Categoria do recebedor. Valores: merchant ou platform. Pela API pública use merchant.

companyType

string

Tipo da empresa (texto livre). Relevante quando type = company.

companyLegalName

string

Razão social.

companyFoundingDate

string

Data de fundação da empresa.

annualRevenue

integer

Faturamento anual, em centavos (inteiro).

corporationType

string

Natureza jurídica (texto livre).

birthDate

string

Data de nascimento. Relevante quando type = individual.

motherName

string

Nome da mãe.

profession

string

Profissão.

monthlyIncome

integer

Renda mensal, em centavos (inteiro).

pixKeyType

string

Tipo da chave Pix.

pixKey

string

Chave Pix.

website

string

Site do recebedor.

legalRepresentativeInfo

object

Dados do representante legal. Campos: name (string, obrigatório), document (string, obrigatório), email (string), motherName (string), birthdate (string), monthlyIncome (number), profession (string), phone (string), selfDeclaredRepresentative (boolean).

address

object

Endereço. Todos os campos são opcionais: address, number, complement, neighborhood, city, state (máx. 2 caracteres), postalCode, referencePoint.

bankAccount

object

Conta bancária para repasse. Campos abaixo.

files

object

Documentos em base64: identificationDocument, selfie, socialContract (todos opcionais).

Objeto `bankAccount`

bankAccount.bankHolderName

string

obrigatório

Nome do titular da conta. Mínimo de 2 caracteres.

bankAccount.bankHolderDocument

string

obrigatório

Documento do titular. Mínimo de 11 caracteres.

bankAccount.bankCode

string

obrigatório

Código do banco. Mínimo de 1 caractere.

bankAccount.bankAgency

string

obrigatório

Agência. Mínimo de 1 caractere.

bankAccount.bankAccount

string

obrigatório

Número da conta. Mínimo de 1 caractere.

bankAccount.bankHolderType

string

Tipo do titular (texto livre).

bankAccount.bankName

string

Nome do banco.

bankAccount.bankAccountDigit

string

Dígito verificador da conta.

bankAccount.bankAccountType

string

Tipo da conta (texto livre).

Exemplo

curl -X POST https://api.sandbox.z2pay.com/recipients \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1f9b2a-3d4e-4a55-9c0b-1e2f3a4b5c6d" \
  -d '{
    "name": "Loja do João ME",
    "email": "contato@lojadojoao.com.br",
    "document": "12345678000190",
    "type": "company",
    "phone": "+5511999998888",
    "bankAccount": {
      "bankHolderName": "Loja do João ME",
      "bankHolderDocument": "12345678000190",
      "bankCode": "341",
      "bankName": "Itaú",
      "bankAgency": "1234",
      "bankAccount": "56789",
      "bankAccountDigit": "0"
    }
  }'

{
  "id": "rec_8x2k9d1p4q",
  "name": "Loja do João ME",
  "email": "contato@lojadojoao.com.br",
  "document": "12345678000190",
  "type": "company",
  "phone": "+5511999998888",
  "kind": "merchant",
  "status": "new",
  "role": "seller",
  "companyId": "comp_a1b2c3d4e5",
  "splitValue": null,
  "splitType": null,
  "createdAt": "2026-06-24T12:00:00.000Z",
  "updatedAt": "2026-06-24T12:00:00.000Z"
}

Atualizar recebedor

PUT /recipients/:id

Atualiza os dados de um recebedor já vinculado à sua company. Todos os campos do corpo são opcionais (envie apenas o que quer alterar) — os campos disponíveis são os mesmos do POST de criação. Retorna 404 se o recebedor não estiver vinculado à sua company. Suporta idempotência via header Idempotency-Key.

string

obrigatório

ID do recebedor (prefixo rec_).

curl -X PUT https://api.sandbox.z2pay.com/recipients/rec_8x2k9d1p4q \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5511988887777"
  }'

{
  "id": "rec_8x2k9d1p4q",
  "name": "Loja do João ME",
  "phone": "+5511988887777",
  "updatedAt": "2026-06-24T12:05:00.000Z"
}

Gerar link KYC

POST /recipients/:id/kyc-link

Gera um link temporário para o recebedor completar/validar seus dados via KYC (Know Your Customer). Use quando o recebedor precisa enviar documentos ou complementar o cadastro antes de ser aprovado para receber repasses. Retorna status 201. Suporta idempotência via header Idempotency-Key. Retorna 404 se o recebedor não estiver vinculado à sua company.

string

obrigatório

ID do recebedor (prefixo rec_).

curl -X POST https://api.sandbox.z2pay.com/recipients/rec_8x2k9d1p4q/kyc-link \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "kycUrl": "https://kyc.z2pay.com/recipient/kyc_tok_9f8e7d6c5b4a",
  "expiresAt": "2026-06-25T12:00:00.000Z"
}

kycUrl

string

URL para o recebedor acessar o fluxo de KYC.

expiresAt

string

Data/hora de expiração do link (ISO 8601 com timezone).

Desvincular recebedor

DELETE /recipients/:id

Remove o vínculo do recebedor com a sua company (soft delete do link). O cadastro global do recebedor não é apagado. Suporta idempotência via header Idempotency-Key.

string

obrigatório

ID do recebedor (prefixo rec_).

curl -X DELETE https://api.sandbox.z2pay.com/recipients/rec_8x2k9d1p4q \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Erros comuns

404 — recebedor não vinculado à sua company (em GET /:id, PUT /:id e POST /:id/kyc-link).
401 — x-api-key ausente ou inválida. Veja Autenticação.
400 — corpo inválido (ex.: documento com menos de 11 caracteres, type fora do enum).

Formato completo dos erros em Erros.

Veja também

Splits

Use recebedores como destino de repasse em pagamentos.

Liquidação

Como e quando os recebedores recebem os valores.

Customers

Gestão de clientes pagadores.

Convenções

Idempotência, paginação e formatos.

​Conceitos

Role (papel)

Status do vínculo

​Endpoints

​Listar recebedores

​Parâmetros de query

​Exemplo

​Buscar recebedor owner

​Buscar recebedor por ID

​Criar recebedor

​Campos do corpo

​Objeto bankAccount

​Exemplo

​Atualizar recebedor

​Gerar link KYC

​Desvincular recebedor

​Erros comuns

​Veja também

Splits

Liquidação

Customers

Convenções

Conceitos

Endpoints

Listar recebedores

Parâmetros de query

Exemplo

Buscar recebedor owner

Buscar recebedor por ID

Criar recebedor

Campos do corpo

Objeto `bankAccount`

Exemplo

Atualizar recebedor

Gerar link KYC

Desvincular recebedor

Erros comuns

Veja também