Recipients (Beneficiarios) - Z2Pay Developers

Los beneficiarios (recipients) son los sellers/merchants que reciben las transferencias de sus ventas. Registras un recipient, este queda vinculado a tu company con un rol (role) y un estado, y a partir de ahí puede ser usado como destino en un split de pago. Un recipient global (CPF/CNPJ único en la plataforma) se vincula a tu company mediante un link. La respuesta de los endpoints combina los datos del recipient (nombre, documento, cuenta bancaria) con los datos del link (status, role, configuración de split).

Todas las solicitudes utilizan el header x-api-key. Consulta Autenticación. La URL base de sandbox es https://api.sandbox.z2pay.com.

Conceptos

Role (rol)

seller (valor por defecto al crear vía API), owner (beneficiario principal de la company) o platform (interno). Hay como máximo 1 owner por company.

Estado del vínculo

new, pending, active, refused o inactive. Un recipient debe estar habilitado para recibir transferencias antes de ser usado en un split.

Recipient owner es el beneficiario principal vinculado a tu company con role: "owner". Usa GET /recipients/owner para identificar al owner sin necesidad de conocer su ID.

Endpoints

Método	Ruta	Descripción
`GET`	`/recipients`	Listado paginado de beneficiarios de la company
`GET`	`/recipients/owner`	Retorna el beneficiario con role `owner`
`GET`	`/recipients/:id`	Busca un beneficiario por ID
`POST`	`/recipients`	Crea o vincula un beneficiario a la company
`PUT`	`/recipients/:id`	Actualiza los datos de un beneficiario
`POST`	`/recipients/:id/kyc-link`	Genera un link KYC para que el beneficiario complete sus datos
`DELETE`	`/recipients/:id`	Desvincula el beneficiario de la company

Listar beneficiarios

GET /recipients

Retorna el listado paginado de beneficiarios vinculados a tu company. Acepta filtros opcionales por email o document. Solo los beneficiarios de tipo merchant aparecen en este listado.

Parámetros de query

page

integer

Página actual (paginación).

limit

integer

Cantidad de ítems por página.

string

Filtra por e-mail exacto del beneficiario. Debe ser un e-mail válido.

document

string

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

Ejemplo

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

La combinación de filtros es restrictiva: si email y document se informan y apuntan a beneficiarios distintos, el listado regresa vacío.

Buscar beneficiario owner

GET /recipients/owner

Retorna el beneficiario vinculado a tu company con role: "owner". Si la company no tiene un owner definido, la respuesta es 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"
}

Cuando no hay owner, el cuerpo de la respuesta es literalmente null (status 200). Maneja ese caso en tu código antes de acceder a cualquier campo.

Buscar beneficiario por ID

GET /recipients/:id

string

requerido

ID del beneficiario (prefijo 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 si el beneficiario no está vinculado a tu company. Consulta Errores.

Crear beneficiario

POST /recipients

Crea un beneficiario (registro global por CPF/CNPJ) y lo vincula a tu company con role: "seller". Si ya existe un beneficiario merchant con el mismo documento o e-mail, se reutiliza y sus datos se actualizan con los que envíes. Retorna status 201. Soporta idempotencia mediante el header Idempotency-Key — consulta Convenciones.

El estado inicial del vínculo depende de los datos enviados: con dirección principal y cuenta bancaria completadas, el vínculo se crea como pending; de lo contrario, se crea como new.

Campos del cuerpo

name

string

requerido

Nombre del beneficiario. Mínimo de 2 caracteres.

string

requerido

E-mail válido del beneficiario.

document

string

requerido

CPF o CNPJ. Mínimo de 11 caracteres.

type

string

requerido

Tipo del beneficiario. Valores: individual o company.

phone

string

Teléfono del beneficiario.

kind

string

Categoría del beneficiario. Valores: merchant o platform. Para la API pública usa merchant.

companyType

string

Tipo de empresa (texto libre). Relevante cuando type = company.

companyLegalName

string

Razón social.

companyFoundingDate

string

Fecha de constitución de la empresa.

annualRevenue

integer

Facturación anual, en centavos (entero).

corporationType

string

Naturaleza jurídica (texto libre).

birthDate

string

Fecha de nacimiento. Relevante cuando type = individual.

motherName

string

Nombre de la madre.

profession

string

Profesión.

monthlyIncome

integer

Ingresos mensuales, en centavos (entero).

pixKeyType

string

Tipo de clave Pix.

pixKey

string

Clave Pix.

website

string

Sitio web del beneficiario.

legalRepresentativeInfo

object

Datos del representante legal. Campos: name (string, obligatorio), document (string, obligatorio), email (string), motherName (string), birthdate (string), monthlyIncome (number), profession (string), phone (string), selfDeclaredRepresentative (boolean).

address

object

Dirección. Todos los campos son opcionales: address, number, complement, neighborhood, city, state (máx. 2 caracteres), postalCode, referencePoint.

bankAccount

object

Cuenta bancaria para transferencias. Ver campos a continuación.

files

object

Documentos en base64: identificationDocument, selfie, socialContract (todos opcionales).

Objeto `bankAccount`

bankAccount.bankHolderName

string

requerido

Nombre del titular de la cuenta. Mínimo de 2 caracteres.

bankAccount.bankHolderDocument

string

requerido

Documento del titular. Mínimo de 11 caracteres.

bankAccount.bankCode

string

requerido

Código del banco. Mínimo de 1 carácter.

bankAccount.bankAgency

string

requerido

Agencia. Mínimo de 1 carácter.

bankAccount.bankAccount

string

requerido

Número de cuenta. Mínimo de 1 carácter.

bankAccount.bankHolderType

string

Tipo de titular (texto libre).

bankAccount.bankName

string

Nombre del banco.

bankAccount.bankAccountDigit

string

Dígito verificador de la cuenta.

bankAccount.bankAccountType

string

Tipo de cuenta (texto libre).

Ejemplo

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

Actualizar beneficiario

PUT /recipients/:id

Actualiza los datos de un beneficiario ya vinculado a tu company. Todos los campos del cuerpo son opcionales (envía solo lo que deseas modificar) — los campos disponibles son los mismos del POST de creación. Retorna 404 si el beneficiario no está vinculado a tu company. Soporta idempotencia mediante el header Idempotency-Key.

string

requerido

ID del beneficiario (prefijo 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"
}

Generar link KYC

POST /recipients/:id/kyc-link

Genera un link temporal para que el beneficiario complete o valide sus datos mediante KYC (Know Your Customer). Úsalo cuando el beneficiario necesite enviar documentos o completar su registro antes de ser aprobado para recibir transferencias. Retorna status 201. Soporta idempotencia mediante el header Idempotency-Key. Retorna 404 si el beneficiario no está vinculado a tu company.

string

requerido

ID del beneficiario (prefijo 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 que el beneficiario acceda al flujo de KYC.

expiresAt

string

Fecha/hora de expiración del link (ISO 8601 con timezone).

Desvincular beneficiario

DELETE /recipients/:id

Elimina el vínculo del beneficiario con tu company (soft delete del link). El registro global del beneficiario no se elimina. Soporta idempotencia mediante el header Idempotency-Key.

string

requerido

ID del beneficiario (prefijo rec_).

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

Errores comunes

404 — beneficiario no vinculado a tu company (en GET /:id, PUT /:id y POST /:id/kyc-link).
401 — x-api-key ausente o inválida. Consulta Autenticación.
400 — cuerpo inválido (ej.: documento con menos de 11 caracteres, type fuera del enum).

Formato completo de los errores en Errores.

Ver también

Splits

Usa beneficiarios como destino de transferencias en pagos.

Liquidación

Cómo y cuándo los beneficiarios reciben los valores.

Customers

Gestión de clientes pagadores.

Convenciones

Idempotencia, paginación y formatos.

​Conceptos

Role (rol)

Estado del vínculo

​Endpoints

​Listar beneficiarios

​Parámetros de query

​Ejemplo

​Buscar beneficiario owner

​Buscar beneficiario por ID

​Crear beneficiario

​Campos del cuerpo

​Objeto bankAccount

​Ejemplo

​Actualizar beneficiario

​Generar link KYC

​Desvincular beneficiario

​Errores comunes

​Ver también

Splits

Liquidación

Customers

Convenciones

Conceptos

Endpoints

Listar beneficiarios

Parámetros de query

Ejemplo

Buscar beneficiario owner

Buscar beneficiario por ID

Crear beneficiario

Campos del cuerpo

Objeto `bankAccount`

Ejemplo

Actualizar beneficiario

Generar link KYC

Desvincular beneficiario

Errores comunes

Ver también