Pular para o conteúdo principal

Manual Cartão Consignado - Webhooks

Navegação
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​

CampoTipoDescrição
keystringChave da reserva do cartão
statusstringNovo status da reserva
webhook_typestringlaas.payroll_card_reservation.status_change
event_datetimestringData e hora do evento
dataobjectObjeto 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, além dos dados da análise facial do assinante .

Exemplo de Payload
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_onboarding",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "attached_documents": [
            {
                "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":"0f0651de-bf3f-45f8-891f-f81b9c24df10",
                "document_type":"payroll_card_consent_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":"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":"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"
            }
        ],
        "signature_data": {
            "document_similarity_score": 1,
            "similarity_score": 0.75,
            "biometry_analysis_reference": "internal",
        }
    }
}
Response Body Details
CampoTipoDescrição
attached_documentsarrayLista de documentos criados para a reserva
signature_dataobjectDados biométricos coletados na assinatura
Payload signature_data​
CampoTipoDescrição
document_similarity_scorenumberNota de similiaridade biométrica entre o assinante e o documento enviado (0-1)
similarity_scorenumberNota de similiaridade biométrica entre o assinante e a referência encontrada na base de rostos (0-1)
biometry_analysis_referencestringBase de origem do rosto utilizado para o calculo da nota de similaridade biométrica

B. Envio de Documentos Adicionais (Pending Additional Documents Submission)​

Ocorre quando o onboarding é aprovado com sucesso OU quando a operação retorna da etapa de validação devido à rejeição do documento adicional (vídeo).

Este webhook indica que a operação está aguardando o envio (ou reenvio) do vídeo de confirmação via endpoint /additional_documents. Caso seja um reenvio por rejeição, o payload retornará o campo rejection_reason.

Exemplo de Payload
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_additional_documents_submission",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T16:00:00Z",
    "data": {
        "rejection_reason": "Vídeo sem áudio ou ilegível" // Presente apenas quando retornando do status pending_additional_documents_validation após a rejeição de um documento
    }
}

C. Validação de Documentos Adicionais (Pending Additional Documents Validation)​

Ocorre após o envio com sucesso do vídeo de confirmação. O status muda para pending_additional_documents_validation, indicando que o vídeo/documento adicional entrou na fila para validação e análise.

Exemplo de Payload
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_additional_documents_validation",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T16:15:00Z",
    "data": {}
}

D. Documentos Adicionais Aprovados (Pending Collateral Reservation)​

Ocorre após a etapa de validação analisar e aprovar o vídeo de confirmação. O status muda para pending_collateral_reservation (aguardando reserva de margem na Dataprev).

Exemplo de Payload
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_collateral_reservation",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T17:00:00Z",
    "data": {}
}

E. Margem Averbada (Pending Withdrawal Disbursement)​

Ocorre quando a margem é reservada com sucesso na Dataprev e a operação de crédito é criada e está aguardando desembolso. O status muda para pending_withdrawal_disbursement (aguardando desembolso do saque).

Exemplo de Payload
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_withdrawal_disbursement",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T17:30:00Z",
    "data": {
        "credit_operation_key": "3571e292-3a83-4011-904d-20ee963022ef"
    }
}

F. 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": "3571e292-3a83-4011-904d-20ee963022ef",
    "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"
    }
}

G. Cartão Emitido (Card Issued)​

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

Exemplo de Payload
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "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"
    }
}

H. 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": "3571e292-3a83-4011-904d-20ee963022ef",
    "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)"
    }
}

2. Webhook de Documentos (Geração e Validação)​

Este webhook notifica alterações nos status individuais de cada documento anexado à operação. Isso inclui a geração de contratos, a etapa de coleta de assinaturas, e as respostas da etapa de validação de documentos adicionais (como o vídeo de confirmação).

WEBHOOK TYPE
laas.payroll_card_reservation.attached_document.status_change

Estrutura Geral do Webhook​

CampoTipoDescrição
keystringChave do documento
statusstringNovo status do documento (generated, pending_signature, approved, rejected)
webhook_typestringlaas.payroll_card_reservation.attached_document.status_change
event_datetimestringData e hora do evento
dataobjectObjeto contendo dados relevantes para a mudança de status

Detalhes do objeto data​

CampoTipoDescrição
payroll_card_reservation_keystringChave da reserva do cartão
document_keystringChave única do documento
document_typestringTipo do documento
document_urlstringLink para visualização do documento
signature_urlstringLink para o fluxo de assinatura. Apenas quando o status é pending_signature.
rejection_reasonstringMotivo da rejeição. Apenas quando o status é rejected.

Cenários​

A. Documento Gerado (generated)​

Ocorre quando os contratos de operação são gerados com sucesso e estão prontos para visualização.

Exemplo de Payload
{
    "key": "332017f4-a0d6-463a-8557-e925a9485251",
    "status": "generated",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
        "document_type": "payroll_card_term",
        "document_url": "https://storage.googleapis.com/example_document.pdf",
        "signature_url": null
    }
}

B. Assinatura Pendente (pending_signature)​

Ocorre quando os contratos estão gerados e prontos para assinatura pelo beneficiário. Retorna a signature_url.

Exemplo de Payload
{
    "key": "332017f4-a0d6-463a-8557-e925a9485251",
    "status": "pending_signature",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
        "document_type": "payroll_card_term",
        "document_url": "https://storage.googleapis.com/example_document.pdf",
        "signature_url": "https://test.sign.qitech.com.br/s/SVomf6J"
    }
}

C. Documento Adicional Aprovado (approved)​

Ocorre como resposta da validação de um documento adicional (como o vídeo de confirmação), indicando que ele foi validado e aceito pelo nosso time ou sistema de checagem.

Exemplo de Payload
{
    "key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
    "status": "approved",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T16:45:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
        "document_type": "payroll_card_confirmation_video",
        "document_url": "https://storage.googleapis.com/video.mp4",
        "signature_url": null
    }
}

D. Documento Adicional Rejeitado (rejected)​

Ocorre como resposta negativa da validação de um documento adicional. Neste cenário, o arquivo foi recusado e o payload incluirá a propriedade rejection_reason informando o porquê.

Exemplo de Payload
{
    "key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
    "status": "rejected",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T16:50:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
        "document_type": "payroll_card_confirmation_video",
        "document_url": "https://storage.googleapis.com/video_bad.mp4",
        "signature_url": null,
        "rejection_reason": "Áudio inaudível e rosto do cliente não visível"
    }
}

3. Webhook de Retorno da Dataprev (Collateral)​

Este webhook notifica sobre o andamento da reserva de margem junto à Dataprev.

É utilizado principalemte em cenários de "Teimosinha", onde falhas temporárias (como margem presa ou valor de parcela excedido momentaneamente) não cancelam a reserva imediatamente. Nesses casos, a reserva permanece na fila de averbação até a última data de desembolso configurada.

WEBHOOK TYPE
social_security.collateral

Estrutura Geral do Webhook​

CampoTipoDescrição
keystringChave da Reserva do Cartão (payroll_card_reservation_key)
webhook_typestringSempre social_security.collateral
event_timestringData e hora do evento
dataobjectDados detalhados do retorno da Dataprev
data.collateral_constitutedbooleanIndica se a garantia foi constituída com sucesso (true ou false)
data.collateral_data.statusstringStatus da reserva (ex: pending_reservation)
data.collateral_data.last_responseobjectContém a lista de erros retornada pela Dataprev (ex: installment_limit_excceded)
Exemplo de Payload - Falha Temporária
{
  "event_time": "2026-01-06 18:48:51",
  "key": "b670553f-28f4-4cf2-a3b5-e33c5ae86bb5",
  "webhook_type": "social_security.collateral",
  "data": {
    "collateral_data": {
      "last_response": {
        "errors": [
          {
            "enumerator": "installment_limit_excceded"
          }
        ]
      },
      "status": "pending_reservation",
      "last_response_event_datetime": "2026-01-06T18:48:51Z",
      "reservation_method": "social_security_payroll_card"
    },
    "collateral_type": "social_security_payroll_card",
    "collateral_constituted": false
  }
}

4. Webhook de Operação de Crédito (Desembolso e Status da CCB)​

Este webhook notifica a mudança de status da Operação de Crédito (CCB) vinculada à reserva. Ele é disparado em dois momentos principais:

  1. Sucesso (opened): O valor foi transferido com sucesso para a conta do cliente.
  2. Cancelamento (canceled): Ocorreu um erro bancário no desembolso (ex: conta inválida, divergência de titularidade) e a operação foi cancelada.
WEBHOOK TYPE
laas.credit_operation.status_change

Estrutura Geral do Webhook​

CampoTipoDescrição
keystringChave da Operação de Crédito (credit_operation_key)
statusstringNovo status da operação: opened (Sucesso) ou canceled (Falha)
webhook_typestringSempre laas.credit_operation.status_change
event_datetimestringData e hora do evento
dataobjectObjeto variável contendo detalhes do sucesso ou motivo do erro

Cenário A: Desembolso com Sucesso (opened)​

Quando o status é opened, o objeto data contém os detalhes financeiros finais e o comprovante da transação.

Campo (dentro de data)TipoDescrição
installmentsarrayLista de parcelas confirmadas com datas e valores finais
transaction_receiptsarrayLista de comprovantes de transferência bancária
requester_identifier_keystringIdentificador único do solicitante
Exemplo de Payload - Sucesso
{
    "key": "550e8400-e29b-41d4-a716-446655440000",
    "status": "opened",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2025-10-14 13:26:52",
    "data": {
      "installments": [
        {
          "due_date": "2025-12-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174000",
          "pre_fixed_amount": 212.35873015,
          "installment_number": 1,
          "principal_amortization_amount": 102.66126985
        },
        {
          "due_date": "2026-01-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174001",
          "pre_fixed_amount": 76.17371273,
          "installment_number": 2,
          "principal_amortization_amount": 238.84628727
        },
        {
          "due_date": "2026-02-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174002",
          "pre_fixed_amount": 59.12264515,
          "installment_number": 3,
          "principal_amortization_amount": 255.89735485
        },
        {
          "due_date": "2026-03-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174003",
          "pre_fixed_amount": 36.77641144,
          "installment_number": 4,
          "principal_amortization_amount": 278.24358856
        },
        {
          "due_date": "2026-04-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174004",
          "pre_fixed_amount": 20.98850053,
          "installment_number": 5,
          "principal_amortization_amount": 294.03149947
        }
      ],
      "disbursement_type": "pix",
      "transaction_receipts": [
        {
          "fee": 0,
          "url": "https://bank-receipt-url.com/receipt.pdf",
          "amount": 1151.15,
          "origin": {
            "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
            "type": "payment_account",
            "branch": "0001",
            "document": "32402502000135",
            "bank_code": "329",
            "account_key": "acc_origin_uuid",
            "branch_digit": null,
            "account_digit": "1",
            "account_branch": "0001",
            "account_number": "1234567",
            "financial_institution_name": "QI SCD S.A."
          },
          "timestamp": "2025-10-14T13:26:52",
          "description": "1234567 - Roberto Alves",
          "destination": {
            "name": "Roberto Alves",
            "type": "checking_account",
            "branch": "0001",
            "purpose": "Crédito PIX em Conta",
            "document": "12345678911",
            "bank_ispb": "12121212",
            "branch_digit": null,
            "account_digit": "2",
            "account_number": "123456",
            "financial_institution_name": "BANCO"
          },
          "end_to_end_id": "E32402502202510141326",
          "transaction_key": "tx_key_uuid",
          "origin_transaction_key": "origin_tx_key_uuid"
        }
      ],
      "requester_identifier_key": "req_id_key_uuid"
    }
}

Cenário B: Falha no Desembolso (canceled)​

Quando o status é canceled, o objeto data contém o motivo da recusa bancária (Pix ou TED devolvido).

Campo (dentro de data)TipoDescrição
cancel_reasonstringMotivo macro do cancelamento (ex: pix_refusal, ted_refusal)
cancel_reason_enumeratorstringEnumerador do motivo (ex: pix_refusal)
pix_refusalobjectDetalhes da recusa caso seja Pix (opcional)
ted_refusalobjectDetalhes da recusa caso seja TED (opcional)
[refusal].reasonstringMensagem descritiva do erro bancário
[refusal].reason_enumeratorstringCódigo do erro bancário (ex: invalid_account)
Exemplo de Payload - Erro no Desembolso
{
    "key": "30e8917d-2b1f-4c79-baf5-cc18bb6e0277",
    "status": "canceled",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2026-01-06 20:57:04",
    "data": {
        "cancel_reason": "pix_refusal",
        "cancel_reason_enumerator": "pix_refusal",
        "pix_refusal": {
            "reason": "Número da conta de destino é inexistente ou inválido.",
            "reason_enumerator": "invalid_account",
            "cancel_reason_enumerator": "invalid_account"
        }
    }
}
Reapresentação

O cancelamento da Operação de Crédito associada a uma reserva não necessariamente implica no cancelamento da reserva em sí. Em casos de erro de desembolso, a reserva permanece aberta e a operação de crédito permanece apta a reapresentação até a data de envio do cartão.

Para mais detalhes, ver tópico 5. Reapresentação de Pagamento do Saque em Criação da Reserva

5. Webhook de Criação da Apólice de Seguro/Benefício​

Este webhook notifica a emissão do seguro associado ao cartão, e retorna a URL da apólice do benefício. A emissão do seguro ocorre de forma assíncrona após a emissão do cartão, podendo demorar algumas horas para ser confirmada.

WEBHOOK TYPE
laas.payroll_card_reservation.benefit.emission

Estrutura Geral do Webhook​

CampoTipoDescrição
keystringChave da Reserva do Cartão (payroll_card_reservation_key)
statusstringactive (Seguro ativo)
webhook_typestringSempre laas.payroll_card_reservation.benefit.emission
event_datetimestringData e hora do evento
dataobjectObjeto variável contendo detalhes da apólice
data.benefit_keystringChave do Benefício/Seguro associado a uma reserva (benefit.benefit_key)
data.policy_urlstringURL do documento da apólice do seguro
Exemplo de Webhook
{
    "key": "550e8400-e29b-41d4-a716-446655440000",
    "status": "active",
    "webhook_type": "laas.payroll_card_reservation.benefit.emission",
    "event_datetime": "2025-10-14 13:26:52",
    "data": {
      "benefit_key": "29dbece4-9f57-40ae-b85c-8e04bf2c4cdf",
      "policy_url": "https://example.com/policy.pdf",
    }
}