Skip to main content

Payroll Card Manual - Webhooks

Navigation
API under development

The API is still in development phase, therefore this manual is subject to changes.

1. Status Change Webhook (Global)​

To track the evolution of the request (Signature completed, Onboarding failure, Disbursement made or Card issued), the API sends a single webhook notifying the status change of the reservation.

WEBHOOK TYPE
laas.payroll_card_reservation.status_change

General Webhook Structure​

FieldTypeDescription
keystringCard reservation key
statusstringNew reservation status
webhook_typestringlaas.payroll_card_reservation.status_change
event_datetimestringEvent date and time
dataobjectObject containing relevant data for the state change

Scenarios​

A. Signature Completed (Pending Onboarding)​

Occurs when documents are signed (via Qi Sign or externally). The reservation status changes to pending_onboarding and the flow proceeds to onboarding.

Returns the list of attached documents of the Reservation, plus the signatory's facial analysis data.

Payload Example
{
    "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
FieldTypeDescription
attached_documentsarrayList of documents created for the reservation
signature_dataobjectBiometric data collected during signature
Payload signature_data​
FieldTypeDescription
document_similarity_scorenumberBiometric similarity score between the signatory and the submitted document (0-1)
similarity_scorenumberBiometric similarity score between the signatory and the reference found in the face database (0-1)
biometry_analysis_referencestringOrigin database of the face used for calculating the biometric similarity score

B. Additional Documents Submission (Pending Additional Documents Submission)​

Occurs when the margin is successfully reserved at Dataprev OR when the operation returns from the validation stage due to additional document (video) rejection.

This webhook indicates that the operation is awaiting the submission (or resubmission) of the confirmation video via the /additional_documents endpoint. In case of resubmission due to rejection, the payload will return the rejection_reason field.

Payload Example
{
    "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": {
        "rejection_reason": "Vídeo sem áudio ou ilegível" // Present only when returning from pending_additional_documents_validation status after document rejection
    }
}

C. Additional Documents Validation (Pending Additional Documents Validation)​

Occurs after successful submission of the confirmation video. The status changes to pending_additional_documents_validation, indicating that the video/additional document has entered the queue for validation and analysis.

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

D. Additional Documents Approved (Pending Withdrawal Disbursement)​

Occurs after the validation stage analyzes and approves the confirmation video. The status changes to pending_withdrawal_disbursement (awaiting withdrawal disbursement).

Payload Example
{
    "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"
    }
}

E. Disbursement Made (Pending Card Issuance)​

Occurs when the withdrawal is executed. The status changes to pending_card_issuance (awaiting card issuance) and the flow proceeds to card issuance.

Returns no additional information.

Payload Example
{
    "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"
    }
}

F. Card Issued (Card Issued)​

Occurs when the wallet and card are created.

Payload Example
{
    "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"
    }
}

G. Cancellation (Canceled)​

Occurs when the operation is cancelled for some reason (Rejection in identity or credit validations, error in margin reservation at Dataprev, etc.).

Returns the cancellation reason and details.

Payload Example
{
    "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. Documents Webhook (Generation and Validation)​

This webhook notifies changes in the individual status of each document attached to the operation. This includes contract generation, the signature collection stage, and responses from the additional document validation stage (such as the confirmation video).

WEBHOOK TYPE
laas.payroll_card_reservation.attached_document.status_change

General Webhook Structure​

FieldTypeDescription
keystringDocument key
statusstringNew document status (generated, pending_signature, approved, rejected)
webhook_typestringlaas.payroll_card_reservation.attached_document.status_change
event_datetimestringEvent date and time
dataobjectObject containing relevant data for the status change

Details of the data object​

FieldTypeDescription
payroll_card_reservation_keystringCard reservation key
document_keystringUnique document key
document_typestringDocument type
document_urlstringLink to view the document
signature_urlstringLink to the signature flow. Only when status is pending_signature.
rejection_reasonstringRejection reason. Only when status is rejected.

Scenarios​

A. Document Generated (generated)​

Occurs when operation contracts are successfully generated and ready for viewing.

Payload Example
{
    "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. Pending Signature (pending_signature)​

Occurs when contracts are generated and ready for signature by the beneficiary. Returns the signature_url.

Payload Example
{
    "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. Additional Document Approved (approved)​

Occurs as a response to validation of an additional document (such as the confirmation video), indicating that it was validated and accepted by our team or checking system.

Payload Example
{
    "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. Additional Document Rejected (rejected)​

Occurs as a negative response to validation of an additional document. In this scenario, the file was rejected and the payload will include the rejection_reason property explaining why.

Payload Example
{
    "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. Dataprev Return Webhook (Collateral)​

This webhook notifies about the progress of margin reservation with Dataprev.

It is mainly used in "Retry" scenarios, where temporary failures (such as locked margin or temporarily exceeded installment value) do not immediately cancel the reservation. In these cases, the reservation remains in the endorsement queue until the last configured disbursement date.

WEBHOOK TYPE
social_security.collateral

General Webhook Structure​

FieldTypeDescription
keystringCard Reservation key (payroll_card_reservation_key)
webhook_typestringAlways social_security.collateral
event_timestringEvent date and time
dataobjectDetailed data from Dataprev return
data.collateral_constitutedbooleanIndicates if the collateral was successfully constituted (true or false)
data.collateral_data.statusstringReservation status (ex: pending_reservation)
data.collateral_data.last_responseobjectContains the list of errors returned by Dataprev (ex: installment_limit_excceded)
Payload Example - Temporary Failure
{
  "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. Credit Operation Webhook (Disbursement and CCB Status)​

This webhook notifies the status change of the Credit Operation (CCB) linked to the reservation. It is triggered at two main moments:

  1. Success (opened): The amount was successfully transferred to the client's account.
  2. Cancellation (canceled): A banking error occurred in disbursement (ex: invalid account, ownership discrepancy) and the operation was cancelled.
WEBHOOK TYPE
laas.credit_operation.status_change

General Webhook Structure​

FieldTypeDescription
keystringCredit Operation key (credit_operation_key)
statusstringNew operation status: opened (Success) or canceled (Failure)
webhook_typestringAlways laas.credit_operation.status_change
event_datetimestringEvent date and time
dataobjectVariable object containing success details or error reason

Scenario A: Successful Disbursement (opened)​

When the status is opened, the data object contains the final financial details and transaction receipt.

Field (inside data)TypeDescription
installmentsarrayList of confirmed installments with final dates and amounts
transaction_receiptsarrayList of bank transfer receipts
requester_identifier_keystringUnique requester identifier
Payload Example - Success
{
    "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"
    }
}

Scenario B: Disbursement Failure (canceled)​

When the status is canceled, the data object contains the reason for banking refusal (returned Pix or TED).

Field (inside data)TypeDescription
cancel_reasonstringMacro reason for cancellation (ex: pix_refusal, ted_refusal)
cancel_reason_enumeratorstringReason enumerator (ex: pix_refusal)
pix_refusalobjectRefusal details if it's Pix (optional)
ted_refusalobjectRefusal details if it's TED (optional)
[refusal].reasonstringDescriptive message of the banking error
[refusal].reason_enumeratorstringBanking error code (ex: invalid_account)
Payload Example - Disbursement Error
{
    "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"
        }
    }
}
Resubmission

The cancellation of the Credit Operation associated with a reservation does not necessarily imply the cancellation of the reservation itself. In cases of disbursement error, the reservation remains open and the credit operation remains eligible for resubmission until the card shipment date.

For more details, see topic 5. Withdrawal Payment Resubmission in Reservation Creation

5. Insurance/Benefit Policy Creation Webhook​

This webhook notifies the issuance of insurance associated with the card, and returns the URL of the benefit policy. Insurance issuance occurs asynchronously after card issuance and may take several hours to be confirmed.

WEBHOOK TYPE
laas.payroll_card_reservation.benefit.emission

General Webhook Structure​

FieldTypeDescription
keystringBenefit/Insurance key associated with a reservation (benefit.benefit_key)
statusstringactive (Active insurance)
webhook_typestringAlways laas.payroll_card_reservation.benefit.emission
event_datetimestringEvent date and time
dataobjectVariable object containing policy details
data.policy_urlstringURL of the insurance policy document
Webhook Example
{
    "key": "550e8400-e29b-41d4-a716-446655440000",
    "status": "opened",
    "webhook_type": "laas.payroll_card_reservation.benefit.emission",
    "event_datetime": "2025-10-14 13:26:52",
    "data": {
      "policy_url": "https://example.com/policy.pdf",
    }
}