> ## 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.
# Gerar link KYC
> Cria um link temporário para o recebedor completar o próprio cadastro, sem passar por você.
`POST /recipients/:id/kyc-link`
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á.
Gera uma URL que o recebedor abre para enviar documentos, completar dados pessoais e fazer a prova
de vida. A resposta é o link e a data em que ele deixa de valer.
**Serve para o que você não pode fazer por ele.** Documento com foto e prova de vida exigem a
presença da pessoa — não há campo de API que substitua. É o caminho quando o recebedor está em
`awaiting_liveness`, ou quando a análise pediu documento que você não tem.
**O link é efêmero: gere um a cada envio, não guarde.** Ele expira na data de `expiresAt`, e um
link vencido no e-mail do recebedor vira suporte. Gere na hora de enviar — chamar a rota de novo
não custa nada e não invalida o cadastro.
**Quem tem o link mexe no cadastro.** Ele autentica pela posse, sem login, porque é assim que o
recebedor consegue completar os dados sozinho. Envie pelo canal do titular e não o deixe em log
nem em URL de analytics.
**Responde `404` se o recebedor não estiver vinculado à sua conta.** A rota exige o vínculo, não
só o cadastro existir.
## Exemplo
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/recipients/rec_v57bi6ruyolouw3cpaq2ofy1k/kyc-link \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```
```json Resposta 201 theme={null}
{
"kycUrl": "https://kyc.z2pay.com/recipient/9f4c1e7a2b8d05364af1c9e0b73d825a",
"expiresAt": "2026-08-11T13:00:00.000Z"
}
```
A resposta tem só esses dois campos — não traz o recebedor. Para acompanhar o que a análise ainda
pede, use [`GET /recipients/{id}`](/pt-BR/recipients/get).
## OpenAPI
````yaml openapi/psp.json POST /recipients/{id}/kyc-link
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/{id}/kyc-link:
post:
tags:
- Recipients
summary: Gerar link KYC
description: >-
Gera um link temporário para o recebedor completar o próprio cadastro —
documentos, dados pessoais e prova de vida. O link é efêmero: gere um
novo a cada envio, em vez de guardar.
operationId: RecipientController_generateKycLink
parameters:
- name: id
in: path
required: true
description: ID do recebedor
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição
schema:
type: string
responses:
'201':
description: Link KYC gerado
content:
application/json:
schema:
type: object
properties:
kycUrl:
type: string
description: >-
URL para conclusão do processo de verificação (KYC) do
recebedor.
expiresAt:
type: string
format: date-time
description: Data e hora em que o registro expira (ISO 8601).
example:
kycUrl: >-
https://kyc.z2pay.com/recipient/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
expiresAt: '2025-07-01T13:45:30.000Z'
'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
'404':
description: Recebedor não encontrado
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: NOT_FOUND
message: Recipient not found
'409':
description: >-
Já existe uma requisição em andamento com esta Idempotency-Key. A
API aguarda a primeira concluir por até 5 segundos antes de
responder assim
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)
````