API v5 - Adição do fluxo de Prova de Vida

Adição do novo objeto kyc_details

Com o objetivo de facilitar a adaptação no novo processo de Validação de Identidade, disponibilizaremos uma webapp em que os recebedores poderão passar pelo processo de KYC com biometria.

No fluxo de criação de um novo recebedor, será disponibilizado um QR Code de acesso ao webapp, que deverá ser renderizado pelo Marketplace e disponibilizado para que o recebedor finalize seu processo de credenciamento.

📘

Status do recebedor e transacional

O recebedor estará apto a transacionar mesmo antes de enviar a prova de vida, com status registration.

Entretanto, ele somente conseguirá movimentar seu saldo após a conclusão do credenciamento e tiver o status active.

Para tornar possível a Validação de Identidade com Prova de Vida (KYC) para os vendedores de marketplaces, um novo objeto chamado kyc_details será adicionado no contrato de recebedores na API v5.

A partir deste objeto e do status do recebedor você poderá acompanhar o processo de análise e credenciamento do recebedor.

📘

Recebedores já existentes

Não será necessário atualizar a base atual de recebedores com o fluxo de KYC (prova de vida)

🚧

Atenção - Data de lançamento

O novo contrato na response do recebedor será disponibilizado no dia 21 de março de 2024.

Fluxo de credenciamento do recebedor:

1. Criar recebedor na rota POST/recipient: No response você receberá as informações com os status recipient.status = registration e kyc_details.status = pending
2. Aguardar o recebedor estar pronto para o processo de kyc: Quando o recebedor estiver pronto você receberá um webhook de recipient.updated com os status recipient.status = affiliation e kyc_details.status = partially_denied
3. Criar link para o preenchimento do KYC na rota POST/recipients/{id}/kyc_link
4. Disponibilizar o link gerado ao recebedor para preenchimento
5. Aguardar o preenchimento do recebedor: Quando o recebedor finalizar o preenchimento do KYC você receberá um webhook de recipient.updated com os status recipient.status=affiliation, kyc_details.status = pending e kyc_details.status_reason = in_analysis
6. Aguardar o retorno da análise do KYC: Após a conclusão da análise você receberá um webhook de recipient.updated com os status variando de acordo com o resultado:
   1. Necessário o repreenchimento do KYC: Retornar ao passo 3, os status retornarão para recipient.status = affiliation e kyc_details.status = partially_denied
   2. Recebedor aprovado: recipient.status = active e kyc_details.status = approved
   3. Recebedor reprovado: recipient.status = inactive e kyc_details.status = denied
      Observação: O motivo da recusa será enviado no status_reason

🚧

Expiração do Link para KYC

O Link/Qrcode de KYC tem uma expiração de 20 minutos. Isso quer dizer que, após passados 20 minutos da criação, o link não irá mais funcionar, e o marketplace precisará criar um novo link para disponibiliza-lo para preenchimento do recebedor.

Especificação do objeto kyc_details

Adição de nova rota de criação de link

Quando o recebedor atingir o status de affiliation e seu kyc_details for partially_denied será necessário realizar o envio do QR Code de acesso ao webapp.

Após o envio, o recebedor fará o preenchimento da prova de vida para prosseguir com o credenciamento.

[Contrato da rota de criação de link]

curl --request POST \
     --url https://api.pagar.me/core/v5/recipients/{id}/kyc_link \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

{
  "base64":"BJ1B51JK2B51KJ2B5=",
  "url": "www.pagar.me/kyc/14214214215",
  "expiration_date": "2024-02-10T20:35:46.046Z"
}

📘

Mudanças de status do recebedor e kyc_details - Webhooks

As atualizações de status após a análise dos dados do recebedor serão realizadas de forma assíncrona.

Por esse motivo para receber as atualizações de status do recebedor, é necessário utilizar o webhookde recipient.updated.