Payroll Card Manual - Tracking

Navigation

Issuance (previous)
Webhooks (next)

API under development

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

1. Payroll card reservation query

Queries the details of a specific reservation through its key (payroll_card_reservation_key) or the request key (request_control_key). Returns a single object containing the reservation details.

GET

/payroll_card_reservation/social_security/[PAYROLL-CARD-RESERVATION-KEY]

GET

/payroll_card_reservation/social_security/request_control_key/[REQUEST-CONTROL-KEY]

Query Params

Query Params

Field	Type	Description
retrieve_document_urls	bool	Whether certain document URLs should be returned. Set to False by default.

retrieve_document_urls Parameter

Enabling this parameter may cause request latencies. Use only when necessary.

Currently, only the benefit.policy_document_url field is impacted by this parameter, but other url fields (such as attached_documents.document_url and attached_documents.signature_url) will be updated to depend on this parameter.

The impacted fields (both currently and in the future) are marked with (*).

Response

Response Body

{
  "request_control_key": "550e8400-e29b-41d4-a716-446655440000",
  "payroll_card_reservation_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "payroll_card_reservation_status": "pending_document_generation",
  "card_holder_document_number": "12345678901",
  "identifier_number": "1234567890",
  "total_limit_amount": 8000.00,
  "reservation_amount": 250.00,
  "reservation_contract_number": "PCR0123456789",
  "wallet_key": null,
  "payroll_card_type": "social_security_payroll_card",
  "signature_url": "https://sandbox.sign.qitech.com.br/s/teste",
  "signature_data": {
      "document_similarity_score": 1,
      "similarity_score": 0.75,
      "biometry_analysis_reference": "internal",
  },
  "withdrawal": {
    "withdrawal_key": "b2c3d4e5-f6g7-8901-bcde-f23456789012",
    "withdrawal_amount": 5600.00,
    "withdrawal_status": "waiting_signature",
    "contract_number": "PCR12345678",
    "disbursement_date": "2025-08-08",
    "withdrawal_data": {
      "disbursement_options": [
        {
          "disbursement_date": "2025-08-08",
          "cet": 0.0262,
          "annual_cet": 0.3643,
          "issue_amount": 5827.36,
          "prefixed_interest_rate": {
            "daily_rate": 0.0008104046,
            "interest_base": "calendar_days",
            "monthly_rate": 0.0246,
            "annual_rate": 0.3386043084
          },
          "installments": [
            {
              "total_amount": 152.5,
              "due_date": "2025-10-10",
              "installment_number": 1
            },
            {
              "total_amount": 152.5,
              "due_date": "2025-11-10",
              "installment_number": 2
            },
            {
              "total_amount": 152.5,
              "due_date": "2025-12-10",
              "installment_number": 3
            }
          ]
        }
      ]
    }
  },
  "payroll_card": {
    "payroll_card_key": "c3d4e5f6-g7h8-9012-cdef-345678901234",
    "payroll_card_status": "pending_issuance",
    "card_limit": 2400.00,
    "card_issuance_entry_amount": 17.28
  },
  "attached_documents": [
    {
      "document_key": "d4e5f6g7-h8i9-0123-defg-456789012345",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "withdrawal_operation_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": null,
      "signature_url": null,
    },
    {
      "document_key": "f6g7h8i9-j0k1-2345-fghi-678901234567",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "payroll_card_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": null,
      "signature_url": null,
    },
    {
      "document_key": "925c0a62-ef98-4891-909b-9955a87ccefb",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "payroll_card_consent_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": null,
      "signature_url": null,
    }
  ],
  "benefit": {
    "benefit_key": "0b80d313-2ade-4a28-be58-38b9219c2b8c",
    "card_insurance_key": "0151934c-b219-458f-98a3-8b0f85c70307",
    "status": "active",
    "due_date": "2036-02-18",
    "policy_document_key": "6363eb63-2e85-4786-bc03-8c1ddd8e2be2",
    "policy_document_url": "https://example.com/policy.pdf"
  }
}

Response Body Details

Field	Type	Description
request_control_key	string	Request identification key
payroll_card_reservation_key	string	Payroll card reservation key
payroll_card_reservation_status	string	Payroll card reservation status
card_holder_document_number	string	Card holder's CPF
identifier_number	string	Operation identifier number
reservation_amount	number	Payroll card reservation amount
reservation_contract_number	string	Dataprev annotation contract number
withdrawal	object	Withdrawal data
payroll_card	object	Payroll card data
attached_documents	array	List of attached documents
payroll_card_type	string	Card type (`social_security_benefit_card` or `social_security_payroll_card`)
wallet_key	string	Unique wallet key created (UUID4)
signature_url	string	Reservation contract signature URL (Only present in payload after signature link generation)
signature_data	object	Biometric data collected during signature (Only present in payload after document signature)
benefit	object	Insurance/benefit data associated with the card (Only present in payload after card issuance)

Payload withdrawal

Field	Type	Description
withdrawal_key	string	Unique withdrawal key
contract_number	string	Withdrawal CCB contract number
withdrawal_amount	number	Calculated disbursement amount for withdrawal CCB
disbursement_date	date	Operation disbursement date
withdrawal_status	string	Withdrawal status
withdrawal_data	object	Detailed withdrawal data

Payload withdrawal_data

Field	Type	Description
prefixed_interest_rate	object	Prefixed interest rate
disbursement_options	array	Available disbursement options

Payload prefixed_interest_rate

Field	Type	Description
daily_rate	number	Daily rate
interest_base	string	Interest calculation base
monthly_rate	number	Monthly rate
annual_rate	number	Annual rate

Payload disbursement_options

Field	Type	Description
disbursement_date	string	Disbursement date
cet	number	Monthly Total Effective Cost
annual_cet	number	Annual Total Effective Cost
total_iof	number	Total IOF amount
disbursed_issue_amount	number	Disbursement amount
issue_amount	number	Issue amount
installments	array	List of installments

Payload installments

Field	Type	Description
total_amount	number	Total installment amount
due_date	string	Due date
installment_number	number	Installment number

Payload payroll_card

Field	Type	Description
payroll_card_key	string	Unique payroll card key
payroll_card_status	string	Payroll card status
card_limit	number	Total calculated card limit
card_issuance_entry_amount	number	Card issuance fee amount

Payload attached_documents

Field	Type	Description
document_key	string	Unique document key
document_batch_key	string	Document batch key
document_type	string	Document type
document_certifier	string	Document certifier
document_status	string	Document status
document_url (*)	string	Document URL
signature_url (*)	string	Signature URL

Payload signature_data

Field	Type	Description
document_similarity_score	number	Biometric similarity score between the signer and the submitted document (0-1)
similarity_score	number	Biometric similarity score between the signer and the reference found in the face database (0-1)
biometry_analysis_reference	string	Origin database of the face used to calculate the biometric similarity score

Payload benefit

Field	Type	Description
benefit_key	string	Unique benefit key (UUID)
status	string	Insurance issuance status (`created`, `pending_emission`, `active`, `canceled` or `inactive`)
policy_document_key	string	Unique policy document key (UUID)
policy_document_url (*)	string	Insurance policy document URL

2. Payroll card reservation query by CPF

Queries the active reservations of a given CPF. Returns a list of objects within the payroll_card_reservations property.

GET

/payroll_card_reservation/social_security/card_holder_document_number/[CARD-HOLDER-DOCUMENT-NUMBER]

Response

Response Body

{
   "payroll_card_reservations": [
      {
        "request_control_key": "d3bc353e-d612-4029-9d77-4dca9171c3b5",
        "payroll_card_reservation_key": "5fb9d810-be74-4d26-959d-c75d10834e93",
        "payroll_card_reservation_status": "card_issued",
        "card_holder_document_number": "12345678901",
        "identifier_number": "1234567890",
        "total_limit_amount": 8000.00,
        "reservation_amount": 250.00,
        "reservation_contract_number": "PCR0123456789",
        "wallet_key": "298e4d37-0f20-4aed-ad66-016f8487afba",
        "payroll_card_type": "social_security_payroll_card",
        "card_holder": {
          "email": "joao.teste@example.com",
          "phone": {
            "number": "352141677",
            "area_code": "11",
            "country_code": "055"
          },
          "address": {
            "city": "Belo Horizonte",
            "state": "MG",
            "number": "7889",
            "street": "Rua Santos",
            "complement": "Apto 243",
            "postal_code": "30112000",
            "neighborhood": "Centro"
          }
        },
        "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": "b098074a-7cba-4b67-81e1-8d587185504b",
              "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": "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"
          },
          {
              "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
              "document_type": "payroll_card_confirmation_video",
              "document_certifier": "electronic_client_side",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/video.mp4"
          }
        ],
      },
      {
        "request_control_key": "d3bc353e-d612-4029-9d77-4dca9171c3b5",
        "payroll_card_reservation_key": "5fb9d810-be74-4d26-959d-c75d10834e93",
        "payroll_card_reservation_status": "pending_withdrawal_disbursement",
        "card_holder_document_number": "12345678901",
        "identifier_number": "1234567890",
        "total_limit_amount": 8000.00,
        "reservation_amount": 250.00,
        "reservation_contract_number": "PCR0123456789",
        "wallet_key": "298e4d37-0f20-4aed-ad66-016f8487afba",
        "payroll_card_type": "social_security_payroll_card",
        "card_holder": {
          "email": "joao.teste@example.com",
          "phone": {
            "number": "352141677",
            "area_code": "11",
            "country_code": "055"
          },
          "address": {
            "city": "Belo Horizonte",
            "state": "MG",
            "number": "7889",
            "street": "Rua Santos",
            "complement": "Apto 243",
            "postal_code": "30112000",
            "neighborhood": "Centro"
          }
        },
        "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": "87c23417-c342-4cc7-81b6-81185b6012ce",
              "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": "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"
          },
          {
              "document_key": "b574b555-e3c9-402a-a869-c4bc27751be8",
              "document_type": "payroll_card_confirmation_video",
              "document_certifier": "electronic_client_side",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/video.mp4"
          }
        ],
      }
   ]
}

3. Status Machines

Payroll Card Reservation

The Payroll Card Reservation entity has the following statuses and transitions:

Status Descriptions

Status	Description
`pending_document_generation`	Waiting for document generation for signature
`pending_onboarding`	Waiting for onboarding and KYC process
`pending_collateral_reservation`	Waiting for collateral reservation
`pending_additional_documents_submission`	Margin annotated. Waiting for confirmation video submission
`pending_additional_documents_validation`	Waiting for confirmation video validation
`pending_withdrawal_disbursement`	Waiting for withdrawal operation disbursement
`pending_card_issuance`	Waiting for wallet creation and card issuance
`card_issued`	Card created and active
`canceled`	Operation canceled

Withdrawal

The Withdrawal entity has the following statuses and transitions:

Status Descriptions

Status	Description
`pending_signature`	Waiting for terms signature
`pending_disbursement`	Waiting for withdrawal operation disbursement
`opened`	Disbursement completed and operation active
`canceled`	Operation canceled

Benefit

The Benefit entity has the following statuses and transitions:

Status Descriptions

Status	Description
`created`	Insurance in processing
`pending_emission`	Waiting for insurance issuance
`active`	Insurance issued and active
`canceled`	Insurance canceled
`inactive`	Insurance expired or inactive

4. Reservation cancellation

Allows the cancellation of the payroll card reservation.

Restrictions

API cancellation is only allowed before withdrawal disbursement (Status: pending_withdrawal_disbursement or earlier). If the withdrawal has already been completed or the card has already been issued, cancellation must be handled via support, as it involves financial reversal.

PATCH

/payroll_card_reservation/social_security/[PAYROLL-CARD-RESERVATION-KEY]/cancel

Response

STATUS

200 (OK)

The request was processed successfully. No content returned (Empty body).

// Empty response body

1. Payroll card reservation query​

Query Params​

Response​

Payload withdrawal​

Payload withdrawal_data​

Payload prefixed_interest_rate​

Payload disbursement_options​

Payload installments​

Payload payroll_card​

Payload attached_documents​

Payload signature_data​

Payload benefit​

2. Payroll card reservation query by CPF​

Response​

3. Status Machines​

Payroll Card Reservation​

Status Descriptions​

Withdrawal​

Status Descriptions​

Benefit​

Status Descriptions​

4. Reservation cancellation​

Response​

1. Payroll card reservation query

Query Params

Response

Payload withdrawal

Payload withdrawal_data

Payload prefixed_interest_rate

Payload disbursement_options

Payload installments

Payload payroll_card

Payload attached_documents

Payload signature_data

Payload benefit

2. Payroll card reservation query by CPF

Response

3. Status Machines

Payroll Card Reservation

Status Descriptions

Withdrawal

Status Descriptions

Benefit

Status Descriptions

4. Reservation cancellation

Response