Gestão de Endereço
- Documentos e Assinatura (anterior)
Durante o processo de Onboarding e KYC, o endereço do beneficiário é validado tanto por nossos processos de análise quanto pelo próprio beneficiário. Além disso, problemas de endereço também podem ser identificados durante a tentativa de entrega do cartão. Em ambos os casos, você será notificado via webhook para realizar a confirmação ou a correção dos dados junto ao beneficiário.
1. Webhook de problema no endereço
Este webhook é disparado quando é identificado um problema relacionado ao endereço do beneficiário. Existem dois cenários possíveis, identificados pelo campo rejected_reason:
address_mismatch: Inconsistência detectada durante o processo de KYC entre o endereço enviado e o endereço em nossa base.delivery_failure: Falha na tentativa de entrega do cartão físico no endereço cadastrado.
Ao receber este webhook, você deve contatar o beneficiário e solicitar a correção dos dados através do endpoint de Atualização de Endereço. Estes webhooks também são informados ao beneficiário final através do aplicativo. No entanto, você deve acompanhar e tratar esses casos independentemente, garantindo que a correção do endereço seja realizada por você ou pelo beneficiário.
delivery_failure)Após o recebimento de um webhook de falha na entrega, você tem um prazo de 10 dias para atualizar o endereço do beneficiário. Caso o prazo não seja cumprido, o cartão físico será cancelado e será necessária uma nova emissão do cartão (endpoint em desenvolvimento).
1.1 Exemplo: Inconsistência de endereço (KYC)
Webhook Body — address_mismatch
{
"key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"webhook_type": "laas.payroll_card_reservation.address",
"status": "pending_card_issuance",
"event_datetime": "2025-01-15T16:45:00Z",
"data": {
"address": {
"city": "Belo Horizonte",
"state": "MG",
"postal_code": "30112000",
"street": "Rua Inexistente",
"number": "000",
"neighborhood": "Savassi"
},
"rejected_reason": "address_mismatch",
"rejection_details": {
"description": "Endereço não encontrado na base de validação"
}
}
}
1.2 Exemplo: Falha na entrega do cartão
Webhook Body — delivery_failure
{
"key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"webhook_type": "laas.payroll_card_reservation.address",
"status": "pending_card_issuance",
"event_datetime": "2025-01-15T16:45:00Z",
"data": {
"address": {
"city": "Belo Horizonte",
"state": "MG",
"postal_code": "30112000",
"street": "Rua das Palmeiras",
"number": "789",
"neighborhood": "Savassi"
},
"rejected_reason": "delivery_failure",
"rejection_details": {
"description": "Tentativa de entrega sem sucesso"
}
}
}
2. Atualização de Endereço
Endpoint utilizado para corrigir o endereço do beneficiário após o recebimento de um webhook de erro de validação.
Caso o beneficiário confirme o endereço, não é necessário enviar uma requisição de atualização de endereço, e o endereço já cadastrado será utilizado para o envio do cartão.
Request
Request Body
{
"address": {
"city": "Belo Horizonte",
"state": "MG",
"number": "789",
"street": "Rua das Palmeiras",
"complement": "Casa 3",
"postal_code": "30112000",
"neighborhood": "Savassi"
}
}
Params Details
| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| city | string | Cidade | Sim |
| state | string | Estado (UF) | Sim |
| number | string | Número | Sim |
| street | string | Logradouro | Sim |
| complement | string | Complemento | Não |
| postal_code | string | CEP (apenas números) | Sim |
| neighborhood | string | Bairro | Sim |
Response
A operação será automaticamente reprocessada no fluxo de KYC, potencialmente resultando em um novo webhook de erro caso seja detectada alguma inconsistência novamente.