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, o cliente 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, o cliente 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, o cliente deve acompanhar e tratar esses casos independentemente, garantindo que a correção do endereço seja realizada pelo cliente ou pelo beneficiário.
delivery_failure)Após o recebimento de um webhook de falha na entrega, o cliente 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 através do endpoint de Reemissão de Cartão.
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": {
"cancel_reason_description": "Endereço não encontrado na base de validação",
"cancel_reason_translation": "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": "card_issued",
"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": {
"cancel_reason_description": "Delivery Failure",
"cancel_reason_translation": "Falha na entrega"
}
}
}
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.
3. Reemissão de Cartão
Endpoint utilizado para cancelar o cartão físico atual e emitir um novo cartão para uma reserva já finalizada (card_issued). Deve ser utilizado quando o cartão ainda está em produção ou entrega (ex.: endereço incorreto, falha de entrega, cartão extraviado antes da ativação).
A reemissão não cancela a reserva, a operação de crédito nem a averbação na Dataprev.
A taxa de produção e de entrega da re-emissão do cartão é cobrada do correspondente bancário automaticamente via sistema.
A reemissão só é permitida enquanto o cartão estiver em produção ou entrega. São aceitos cartões nos seguintes status: building, embossing ou canceled. Cartões já ativos (active) não podem ser reemitidos por este endpoint.
Opcionalmente, é possível enviar um novo endereço de entrega no corpo da requisição. Quando informado, o endereço do beneficiário na reserva é atualizado e o novo cartão é produzido/entregue neste endereço.
Request
Request Body (opcional)
{
"delivery_address": {
"city": "Belo Horizonte",
"state": "MG",
"number": "789",
"street": "Rua das Palmeiras",
"complement": "Casa 3",
"postal_code": "30112000",
"neighborhood": "Savassi"
}
}
O corpo da requisição é opcional. Caso não seja enviado, o novo cartão será emitido utilizando o endereço atualmente cadastrado na reserva.
Request Body Details
| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| delivery_address | object | Novo endereço de entrega. Quando enviado, também atualiza o endereço cadastrado na reserva. | Não |
Payload delivery_address
| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| city | string | Cidade | Mínimo: 1 caractere | Sim |
| state | string | Estado (UF) | 2 caracteres | Sim |
| number | string | Número | Mínimo: 1 caractere | Sim |
| street | string | Logradouro | Mínimo: 1 caractere | Sim |
| complement | string | Complemento | Mínimo: 1 caractere | Não |
| postal_code | string | CEP (apenas números) | 8 dígitos numéricos | Sim |
| neighborhood | string | Bairro | Mínimo: 1 caractere | Sim |
Response
Retorna o DTO completo da reserva do cartão consignado, já com o novo payroll_card (nova payroll_card_key, card_key e payment_instrument_key). A estrutura do retorno é a mesma descrita na criação da reserva.