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, além dos dados da análise facial do assinante .

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":"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

Campo	Tipo	Descrição
attached_documents	array	Lista de documentos criados para a reserva
signature_data	object	Dados biométricos coletados na assinatura

Payload signature_data

Campo	Tipo	Descrição
document_similarity_score	number	Nota de similiaridade biométrica entre o assinante e o documento enviado (0-1)
similarity_score	number	Nota de similiaridade biométrica entre o assinante e a referência encontrada na base de rostos (0-1)
biometry_analysis_reference	string	Base de origem do rosto utilizado para o calculo da nota de similaridade biométrica

B. Margem Averbada (Pending Additional Documents Submission)

Ocorre quando a margem é reservada com sucesso na Dataprev. O status muda para pending_additional_documents_submission.

Este webhook indica que a operação está aguardando o envio do vídeo de confirmação via endpoint /additional_documents.

Exemplo de Payload

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

C. Documentos Adicionais Recebidos (Pending Withdrawal Disbursement)

Ocorre após o envio e processamento com sucesso do vídeo de confirmação. O status muda para pending_withdrawal_disbursement (aguardando desembolso do saque).

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"
    }
}

D. 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"
    }
}

E. 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"
    }
}

F. 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)"
    }
}

2. 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

Campo	Tipo	Descrição
key	string	Chave da Reserva do Cartão (`payroll_card_reservation_key`)
webhook_type	string	Sempre `social_security.collateral`
event_time	string	Data e hora do evento
data	object	Dados detalhados do retorno da Dataprev
data.collateral_constituted	boolean	Indica se a garantia foi constituída com sucesso (`true` ou `false`)
data.collateral_data.status	string	Status da reserva (ex: `pending_reservation`)
data.collateral_data.last_response	object	Conté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
  }
}

3. 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:

Sucesso (opened): O valor foi transferido com sucesso para a conta do cliente.
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

Campo	Tipo	Descrição
key	string	Chave da Operação de Crédito (`credit_operation_key`)
status	string	Novo status da operação: `opened` (Sucesso) ou `canceled` (Falha)
webhook_type	string	Sempre `laas.credit_operation.status_change`
event_datetime	string	Data e hora do evento
data	object	Objeto 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`)	Tipo	Descrição
installments	array	Lista de parcelas confirmadas com datas e valores finais
transaction_receipts	array	Lista de comprovantes de transferência bancária
requester_identifier_key	string	Identificador ú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`)	Tipo	Descrição
cancel_reason	string	Motivo macro do cancelamento (ex: `pix_refusal`, `ted_refusal`)
cancel_reason_enumerator	string	Enumerador do motivo (ex: `pix_refusal`)
pix_refusal	object	Detalhes da recusa caso seja Pix (opcional)
ted_refusal	object	Detalhes da recusa caso seja TED (opcional)
[refusal].reason	string	Mensagem descritiva do erro bancário
[refusal].reason_enumerator	string	Có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 1.3.7.11. Reapresentação de dados bancários em API Reference

Manual Cartão Consignado - Webhook

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

Estrutura Geral do Webhook​

Cenários​

A. Assinatura Concluída (Pending Onboarding)​

Payload signature_data​

B. Margem Averbada (Pending Additional Documents Submission)​

C. Documentos Adicionais Recebidos (Pending Withdrawal Disbursement)​

D. Desembolso Realizado (Pending Card Issuance)​

E. Cartão Emitido (Card Issued)​

F. Cancelamento (Canceled)​

2. Webhook de Retorno da Dataprev (Collateral)​

Estrutura Geral do Webhook​

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

Estrutura Geral do Webhook​

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

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

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

Estrutura Geral do Webhook

Cenários

A. Assinatura Concluída (Pending Onboarding)

Payload signature_data

B. Margem Averbada (Pending Additional Documents Submission)

C. Documentos Adicionais Recebidos (Pending Withdrawal Disbursement)

D. Desembolso Realizado (Pending Card Issuance)

E. Cartão Emitido (Card Issued)

F. Cancelamento (Canceled)

2. Webhook de Retorno da Dataprev (Collateral)

Estrutura Geral do Webhook

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

Estrutura Geral do Webhook

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

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