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

🚧

Atenção - Data de Lançamento

As alterações de contrato do recebedor serão disponibilizadas no dia 21 de março de 2024.

👍

Versões de integração v1 a v3

Todas as nossas versões anteriores são retrocompatíveis com a v4, ou seja, todas as alterações realizamos para esta versão de integração estarão também disponíveis nas demais versões, seguindo o mesmo contrato e obrigatoriedades.

Adição do novo objeto kyc_details

Para criação de KYC para recebedores veja aqui.

Com o objetivo de facilitar a adaptação ao novo processo de Validação de Identidade, disponibilizaremos uma rota direta para a webapp em que os recebedores poderão passar pelo processo de KYC biométrico com prova de vida de forma totalmente autônoma.

Após a criação de um recebedor, disponibilizaremos o endpoint de criação do QR Code de acesso a webapp, que deverá ser renderizado pelo Marketplace por uma ação do recebedor e disponibilizado para que finalize seu processo de ativação da sua loja com a Pagar.me.

📘

Importante - Transacional

O recebedor estará apto a transacionar mesmo antes de concluir o processo de prova de vida, porém para movimentar seu saldo é necessário concluir e ser aprovador no KYC.

Adicionaremos o objeto kyc_details ao contrato de recebedores na API v4 e a partir deste objeto e do status será possível acompanhar o processo de análise e ativação do recebedor.

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. Na criação ainda não é retornado kyc_details.
2. Aguardar o recebedor estar pronto para o processo de kyc: Quando o recebedor estiver pronto você receberá um webhook de recipient_status_changed com os status recipient.status = affiliation , kyc_details.status = partially_denied e kyc_details.status_reason = additional_documents_required
   1. Existem cenários no qual o recebedor já foi rejeitado na análise de risco diretamente sem a oportunidade de passar por biometria. Nesses casos, os retornos serão pelo mesmo webhook e sempre com o recipient.status = refused. Os campos de poderão ser enviados como kyc_details.status = denied e kyc_details.status_reason = fully_denied ou poderão não ser enviados.
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 e análise do KYC: Quando o recebedor finalizar o preenchimento do KYC, você receberá um webhook de recipient_status_changed com os status variando de acordo com o resultado:
   1. Recebedor aprovado: recipient.status = active, kyc_details.status = approved ekyc_details.status_reason = ok
   2. Recebedor reprovado: recipient.status = refused ,kyc_details.status = denied ekyc_details.status_reason = fully_denied. Não há mais ações possíveis para credenciar este cliente em nossa base. Para entender o motivo de recusa, deve-se entrar em contato com o time de atendimento

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/1/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 - postback

As atualizações de status após a análise dos dados do recebedor serão realizadas de forma assíncrona. Os webhooks são disparados com base na alteração de status do recebedor e não com a alteração de status do KYC.

Por esse motivo para receber as atualizações de status do recebedor, é necessário utilizar o [postback] de recipient_status_changed

Demonstração fluxo de prova de vida