Manual Cartão Consignado - Webhook

API em desenvolvimento

A API ainda está em fase de desenvolvimento, sendo assim, este manual esta sujeito a alterações.

---

1. Webhook de Alteração de Status (Global)

Para acompanhar a evolução do pedido (Assinatura concluída, Falha no Onboarding, Desembolso realizado ou Cartão Emitido), a API envia um webhook único notificando a mudança de status da reserva.

WEBHOOK TYPE

laas.payroll_card_reservation.status_change

Estrutura Geral do Webhook

Campo	Tipo	Descrição
key	string	Chave da reserva do cartão
status	string	Novo status da reserva
webhook_type	string	laas.payroll_card_reservation.status_change
event_datetime	string	Data e hora do evento
data	object	Objeto contendo dados relevantes para a mudança de estado

Cenários

A. Assinatura Concluída (Pending Onboarding)

Ocorre quando os documentos são assinados (via Qi Sign ou externamente). O status da reservation muda para pending_onboarding e o fluxo segue para onboarding.

Retorna a lista dos attached documents da Reserva

Exemplo de Payload

{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending_onboarding",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "attached_documents": [
            {
                "document_key":"910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
                "document_type":"withdrawal_operation_term",
                "document_certifier":"qi_sign",
                "document_status":"signed",
                "document_batch_key":"f28bf87a-11cd-4d89-89c0-19229a1b31a7",
                "document_url": "https://storage.googleapis.com/example_document.pdf",
                "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
            },
            {
                "document_key":"332017f4-a0d6-463a-8557-e925a9485251",
                "document_type":"payroll_card_term",
                "document_certifier":"qi_sign",
                "document_status":"signed",
                "document_batch_key":"f28bf87a-11cd-4d89-89c0-19229a1b31a7",
                "document_url": "https://storage.googleapis.com/example_document.pdf",
                "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
            },
            {
                "document_key":"b1c3e915-6707-49f5-85a9-398ef997fdad",
                "document_type":"selfie",
                "document_certifier":"qi_sign",
                "document_status":"generated",
                "document_url":"https://storage.googleapis.com/selfie.jpeg"
            },
            {
                "document_key":"5769a335-a2ac-4913-a742-38b9d1e4abd2",
                "document_type":"document_identification",
                "document_certifier":"qi_sign",
                "document_status":"generated",
                "document_url":"https://storage.googleapis.com/cnh.jpeg"
            },
            {
                "document_key":"75577d34-4ebd-4488-aca8-b064e603c973",
                "document_type":"document_identification_back",
                "document_certifier":"qi_sign",
                "document_status":"generated",
                "document_url":"https://storage.googleapis.com/cnh_back.jpeg"
            }
        ]
    }
}

B. Margem Averbada (Pending Withdrawal Disbursement)

Ocorre quando a margem é reservada com sucesso na Dartaprev. O status muda para pending_withdrawal_disbursement (aguardando desembolso do saque).

Retorna a chave da operação de crédito (credit_operation_key) associada à reserva.

Exemplo de Payload

{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending_withdrawal_disbursement",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T17:00:00Z",
    "data": {
        "credit_operation_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
}

C. Desembolso Realizado (Pending Card Issuance)

Ocorre quando o saque é efetivado. O status muda para pending_card_issuance (aguardando emissão do cartão) e o fluxo segue para a emissão do cartão.

Não retorna nenhuma informação adicional.

Exemplo de Payload

{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending_card_issuance",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T17:00:00Z",
    "data": {
        "wallet_key": "9a7b7982-8bf7-4a2c-942c-588166811623"
    }
}

D. Cartão Emitido (Card Issued)

Ocorre quando a wallet e o cartão são criados.

Exemplo de Payload

{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "card_issued",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T18:30:00Z",
    "data": {
        "card_key": "7c6b421e-7ae0-4419-b021-87bcc0be8748"
    }
}

---

E. Cancelamento (Canceled)

Ocorre quando a operação é cancelada por algum motivo (Rejeição nas validações de identidade ou crédito, erro na reserva da margem na Dataprev, etc).

Retorna o motivo do cancelamento e detalhes.

Exemplo de Payload

{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "canceled",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T16:45:00Z",
    "data": {
        "cancel_reason": "not_eligible", 
        "cancel_details": "Age 15 is not within the eligible range (18-79 years)"
    }
}