Manual Cartão Benefício

API em desenvolvimento

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

Consultas de Benefícios

Para consulta de dados do benefício e consulta da lista de benefícios, visite os seguintes itens na documentação do INSS:

1. Consulta de elegibilidade do beneficiário

A consulta de elegibilidade permite verificar se um CPF está elegível para o cartão benefício do INSS. Esta operação é síncrona e retorna imediatamente o resultado da verificação.

Em posse dos dados de CPF e data de nascimento, é possível consultar a elegibilidade do beneficiário. Atualmente, a única validação de elegibilidade realizada é se a idade do beneficiário está entre 18 e 79 anos.

Request

GET

/payroll_card_reservation/social_security/eligibility

Params

Campo	Tipo	Descrição	Obrigatório	Formatação
document_number	string	Número de CPF do beneficiário	Sim	11 dígitos numéricos
birth_date	date	Data de nascimento	Sim	YYYY-MM-DD

Response

STATUS

200 (OK)

Exemplos de Response

Elegível:

{
    "status": "eligible"
}

Não elegível - Idade fora do intervalo:

{
    "status": "not_eligible",
    "error_description": "Age 85 is not within the eligible range (18-79 years)"
}

Response Body Details

Campo	Tipo	Descrição
status	string	Status da elegibilidade (eligible/not_eligible)
error_description	string	Descrição do erro quando não elegível (opcional)

2. Simulação de saque e limite do cartão

A simulação permite calcular o valor de saque disponível e o limite do cartão benefício baseado nos parâmetros financeiros informados. Esta operação é útil para apresentar ao beneficiário as condições antes da contratação.

Request

POST

/payroll_card_reservation/social_security/simulation

Request Body

{
    "financial": {
    "salary_amount": 8000.00,
    "number_of_installments": 96,
    "monthly_interest_rate": 0.0246
  },
  "withdrawal": {
    "disbursement_date": "2025-12-15",
    "limit_days_to_disburse": 5
  },
  "collateral": {
    "collateral_type": "social_security_benefit_card"
  }
}

Request Body Details

Campo	Tipo	Descrição	Formatação	Obrigatório
financial	object	Dados financeiros da operação	-	Sim
withdrawal	object	Dados do saque	-	Sim
collateral	object	Dados do colateral	-	Sim

Payload financial

Campo	Tipo	Descrição	Formatação	Obrigatório
salary_amount	number	Valor do salário do beneficiário	Mínimo: 1 dígito numérico	Sim
number_of_installments	number	Número de parcelas da CCB de saque	Mínimo: 1, Máximo: 96	Sim
monthly_interest_rate	number	Taxa de juros mensal da CCB de saque	Máximo: 0.0246	Sim

Payload withdrawal

Campo	Tipo	Descrição	Formatação	Obrigatório
disbursement_date	date	Data do desembolso da CCB de saque	YYYY-MM-DD	Sim
limit_days_to_disburse	number	Número de dias limite para desembolso da CCB de saque	Mínimo: 1, Máximo: 10	Sim

Payload collateral

Campo	Tipo	Descrição	Formatação	Obrigatório
collateral_type	string	Tipo do cartão benefício	Enum: "social_security_benefit_card", "social_security_payroll_card"	Sim

Response

STATUS

201 (Created)

Response Body

{
    "withdrawal": {
    "withdrawal_amount": 5600.00,
    "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": 164.79,
              "due_date": "2025-10-10",
              "installment_number": 1
            },
            {
              "total_amount": 164.79,
              "due_date": "2025-11-10",
              "installment_number": 2
            },
            {
              "total_amount": 164.79,
              "due_date": "2025-12-10",
              "installment_number": 3
            }
          ]
        }
      ]
    }
  },
  "payroll_card": {
    "card_limit": 2400.00
  },
  "reservation_amount": 800.00
}

Response Body Details

Campo	Tipo	Descrição
withdrawal	object	Dados do saque
withdrawal.withdrawal_amount	number	Valor de desembolso calculado para CCB de saque
withdrawal.withdrawal_data	object	Dados detalhados do saque
payroll_card	object	Dados do cartão benefício
payroll_card.card_limit	number	Limite total calculado para o cartão
reservation_amount	number	Valor da reserva do cartão benefício

Payload withdrawal.withdrawal_data

Campo	Tipo	Descrição
disbursement_options	array	Opções de desembolso disponíveis

Payload disbursement_options

Campo	Tipo	Descrição
disbursement_date	string	Data do desembolso
cet	number	Custo Efetivo Total mensal
annual_cet	number	Custo Efetivo Total anual
issue_amount	number	Valor de emissão
prefixed_interest_rate	object	Taxa de juros prefixada
installments	array	Lista de parcelas

Payload prefixed_interest_rate

Campo	Tipo	Descrição
daily_rate	number	Taxa diária
interest_base	string	Base de cálculo dos juros
monthly_rate	number	Taxa mensal
annual_rate	number	Taxa anual

Payload installments

Campo	Tipo	Descrição
total_amount	number	Valor total da parcela
due_date	string	Data de vencimento
installment_number	number	Número da parcela

3. Criação da operação de saque e geração do termo

A criação da operação de saque inicia o processo de contratação do cartão benefício. Esta operação cria a reserva do cartão, gera os documentos necessários e retorna as chaves para acompanhamento do processo.

POST

/payroll_card_reservation/social_security

Request

Request Body

{
  "card_holder": {
    "name": "Carlos Eduardo Lima",
    "email": "carlos.lima@email.com",
    "phone": {
      "number": "654321098",
      "area_code": "31",
      "country_code": "055"
    },
    "gender": "male",
    "address": {
      "city": "Belo Horizonte",
      "state": "MG",
      "number": "789",
      "street": "Rua das Palmeiras",
      "complement": "Casa 3",
      "postal_code": "30112000",
      "neighborhood": "Savassi"
    },
    "birth_date": "1990-09-18",
    "mother_name": "Fernanda Lima",
    "nationality": "Brasileiro",
    "document_number": "55566677788",
    "document_identification": {
      "document_identification_date": "2012-05-20",
      "document_identification_type": "rg",
      "document_identification_number": "555666777"
    }
  },
  "withdrawal": {
    "disbursement_date": "2025-12-15",
    "limit_days_to_disburse": 5,
    "contract_number": "ABC1234567890",
    "rebates": [{}],
    "disbursement_bank_accounts": [
      {
        "name": "Carlos Eduardo Lima",
        "bank_code": "104",
        "account_digit": "3",
        "branch_number": "5678",
        "account_number": "987654321",
        "document_number": "55566677788",
        "transfer_method": "pix",
        "percentage_receivable": 100,
        "account_type":"checking_account"
      }
    ]
  },
  "financial": {
    "salary_amount": 8000.00,
    "number_of_installments": 96,
    "monthly_interest_rate": 0.0246,
    "fine_configuration": {
      "monthly_rate": 0.025,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.015
    }
  },
  "collateral": {
    "state": "MG",
    "benefit_number": "5556667777",
    "collateral_type": "social_security_benefit_card",
    "subcorban_document_number": "12123456000101"
  },
  "purchaser_document_number": "55566677000177",
  "credit_agent": {
    "document_number": "44455566677",
    "name": "Agente de Crédito Lima"
  },
  "related_parties": [
    {
      "name": "Pedro Costa",
      "email": "pedro.costa@email.com",
      "phone": {
        "number": "765432109",
        "area_code": "21",
        "country_code": "055"
      },
      "address": {
        "city": "Rio de Janeiro",
        "state": "RJ",
        "number": "789",
        "street": "Rua Ipanema",
        "complement": "Apto 12",
        "postal_code": "22080001",
        "neighborhood": "Ipanema"
      },
      "role_type": "issuer",
      "person_type": "natural",
      "is_pep": false,
      "individual_document_number": "11122233344",
      "birth_date": "1980-12-05",
      "mother_name": "Lucia Costa"
    }
  ],
  "request_identifier_key": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Details

Campo	Tipo	Descrição	Formatação	Obrigatório
card_holder	object	Dados do portador do cartão	-	Sim
withdrawal	object	Dados do saque	-	Sim
financial	object	Dados financeiros da operação	-	Sim
collateral	object	Dados do colateral	-	Sim
purchaser_document_number	string	CNPJ do comprador	14 dígitos numéricos	Sim
credit_agent	object	Dados do agente de crédito	-	Sim
related_parties	array	Lista de partes relacionadas	-	Não
request_identifier_key	string	Chave de identificação da requisição	UUID v4	Sim

Payload card_holder

Campo	Tipo	Descrição	Formatação	Obrigatório
name	string	Nome completo do portador	Mínimo: 1 caractere	Sim
email	string	Email do portador	Formato de email válido	Sim
phone	object	Dados do telefone	-	Sim
gender	string	Gênero (male/female)	Enum: "male", "female", "other"	Sim
address	object	Endereço do portador	-	Sim
birth_date	date	Data de nascimento	YYYY-MM-DD	Sim
mother_name	string	Nome da mãe	Mínimo: 1 caractere	Sim
nationality	string	Nacionalidade	Mínimo: 1 caractere	Sim
document_number	string	CPF do portador	11 dígitos numéricos	Sim
document_identification	object	Dados do documento de identificação	-	Sim

Payload phone

Campo	Tipo	Descrição	Formatação	Obrigatório
number	string	Número do telefone	Apenas números	Sim
area_code	string	Código de área	Apenas números	Sim
country_code	string	Código do país	Apenas números	Sim

Payload address

Campo	Tipo	Descrição	Formatação	Obrigatório
city	string	Cidade	Mínimo: 1 caractere	Sim
state	string	Estado	2 caracteres	Sim
number	string	Número	Mínimo: 1 caractere	Sim
street	string	Rua	Mínimo: 1 caractere	Sim
complement	string	Complemento	-	Não
postal_code	string	CEP	8 dígitos numéricos	Sim
neighborhood	string	Bairro	Mínimo: 1 caractere	Sim

Payload document_identification

Campo	Tipo	Descrição	Formatação	Obrigatório
document_identification_date	date	Data de emissão do documento	YYYY-MM-DD	Sim
document_identification_type	string	Tipo do documento (rg)	Enum: "rg", "passport", "other"	Sim
document_identification_number	string	Número do documento	Mínimo: 1 caractere	Sim

Payload withdrawal

Campo	Tipo	Descrição	Formatação	Obrigatório
disbursement_date	date	Data do desembolso	YYYY-MM-DD	Sim
limit_days_to_disburse	number	Número de dias limite para desembolso	Mínimo: 1, Máximo: 10	Sim
contract_number	string	Número do contrato	3 letras maiúsculas + 10 números	Não
rebates	array	Lista de abatimentos	Mínimo: 1 item	Sim
disbursement_bank_accounts	array	Contas bancárias para desembolso	Mínimo: 1 item	Sim

Payload disbursement_bank_accounts

Campo	Tipo	Descrição	Formatação	Obrigatório
name	string	Nome do titular da conta	Mínimo: 1 caractere	Sim
bank_code	string	Código do banco	Apenas números	Sim
account_digit	string	Dígito da conta	Apenas números	Sim
branch_number	string	Número da agência	Apenas números	Sim
account_number	string	Número da conta	Apenas números	Sim
document_number	string	CPF do titular	11 dígitos numéricos	Sim
transfer_method	string	Método de transferência	Enum: "pix", "ted"	Sim
account_type	string	Tipo de conta	Enum: "checking_account","deposit_account","guaranteed_account","investment_account","payment_account","saving_account","salary_account"	Sim
percentage_receivable	number	Percentual a receber	Mínimo: 0, Máximo: 100	Sim

Payload financial

Campo	Tipo	Descrição	Formatação	Obrigatório
salary_amount	number	Valor do salário do beneficiário	Mínimo: 1	Sim
number_of_installments	number	Número de parcelas da CCB de saque	Mínimo: 1, Máximo: 96	Sim
monthly_interest_rate	number	Taxa de juros mensal da CCB de saque	Mínimo: 0.01, Máximo: 0.1	Sim
fine_configuration	object	Configuração de multa	-	Sim

Payload fine_configuration

Campo	Tipo	Descrição	Formatação	Obrigatório
monthly_rate	number	Taxa mensal de multa	Mínimo: 0	Sim
interest_base	string	Base de cálculo dos juros	Enum: "calendar_days", "business_days"	Sim
contract_fine_rate	number	Taxa de multa contratual	Mínimo: 0	Sim

Payload collateral

Campo	Tipo	Descrição	Formatação	Obrigatório
state	string	Estado	2 caracteres	Sim
benefit_number	string	Número do benefício	Mínimo: 1 caractere	Sim
collateral_type	string	Tipo da garantia	Enum: "social_security_benefit_card"	Sim

Payload credit_agent

Campo	Tipo	Descrição	Formatação	Obrigatório
document_number	string	CPF do agente de crédito	11 ou 14 dígitos numéricos	Sim
name	string	Nome do agente de crédito	Mínimo: 1 caractere	Sim

Payload related_parties

Campo	Tipo	Descrição	Formatação	Obrigatório
name	string	Nome da parte relacionada	Mínimo: 1 caractere	Sim
email	string	Email da parte relacionada	Formato de email válido	Sim
phone	object	Dados do telefone	-	Sim
address	object	Endereço da parte relacionada	-	Sim
role_type	string	Tipo de papel (issuer)	Enum: "issuer_legal_representative", "issuer_attorney", "issuer"	Sim
person_type	string	Tipo de pessoa (natural)	Enum: "natural", "signer"	Sim
is_pep	boolean	Se é pessoa politicamente exposta	true/false	Sim
individual_document_number	string	CPF da parte relacionada	11 dígitos numéricos	Sim
birth_date	date	Data de nascimento	YYYY-MM-DD	Sim
mother_name	string	Nome da mãe	Mínimo: 1 caractere	Sim

Response

STATUS

201 (Created)

Response Body

{
  "request_identifier_key": "550e8400-e29b-41d4-a716-446655440000",
  "payroll_card_reservation_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "payroll_card_reservation_status": "pending_document_generation",
  "card_holder_document_number": "12345678901",
  "identifier_number": "1234567890",
  "reservation_amount": 8000.00,
  "withdrawal": {
    "withdrawal_key": "b2c3d4e5-f6g7-8901-bcde-f23456789012",
    "withdrawal_amount": 5600.00,
    "withdrawal_status": "waiting_signature",
    "contract_number": "PCR000123CES",
    "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": 164.79,
              "due_date": "2025-10-10",
              "installment_number": 1
            },
            {
              "total_amount": 164.79,
              "due_date": "2025-11-10",
              "installment_number": 2
            },
            {
              "total_amount": 164.79,
              "due_date": "2025-12-10",
              "installment_number": 3
            }
          ]
        }
      ]
    }
  },
  "payroll_card": {
    "payroll_card_key": "c3d4e5f6-g7h8-9012-cdef-345678901234",
    "payroll_card_status": "pending_creation",
    "card_limit": 2400.00
  },
  "attached_documents": [
    {
      "document_key": "d4e5f6g7-h8i9-0123-defg-456789012345",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "withdrawal_contract",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": "",
      "signature_url": "",
    },
    {
      "document_key": "f6g7h8i9-j0k1-2345-fghi-678901234567",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "card_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": None,
      "signature_url": None,
    }
  ]
}

Response Body Details

Campo	Tipo	Descrição
request_identifier_key	string	Chave de identificação da requisição
payroll_card_reservation_key	string	Chave da reserva do cartão benefício
payroll_card_reservation_status	string	Status da reserva do cartão benefício
card_holder_document_number	string	CPF do portador do cartão
identifier_number	string	Número identificador da operação
reservation_amount	number	Valor da reserva do cartão benefício
withdrawal	object	Dados do saque
payroll_card	object	Dados do cartão benefício
attached_documents	array	Lista de documentos anexados

Payload withdrawal

Campo	Tipo	Descrição
withdrawal_key	string	Chave única do saque
contract_number	string	Número do contrato da CCB de saque
withdrawal_amount	number	Valor de desembolso calculado para CCB de saque
withdrawal_status	string	Status do saque
withdrawal_data	object	Dados detalhados do saque

Payload withdrawal_data

Campo	Tipo	Descrição
disbursement_options	array	Opções de desembolso disponíveis

Payload disbursement_options

Campo	Tipo	Descrição
disbursement_date	string	Data do desembolso
cet	number	Custo Efetivo Total mensal
annual_cet	number	Custo Efetivo Total anual
issue_amount	number	Valor de emissão
prefixed_interest_rate	object	Taxa de juros prefixada
installments	array	Lista de parcelas

Payload prefixed_interest_rate

Campo	Tipo	Descrição
daily_rate	number	Taxa diária
interest_base	string	Base de cálculo dos juros
monthly_rate	number	Taxa mensal
annual_rate	number	Taxa anual

Payload installments

Campo	Tipo	Descrição
total_amount	number	Valor total da parcela
due_date	string	Data de vencimento
installment_number	number	Número da parcela

Payload payroll_card

Campo	Tipo	Descrição
payroll_card_key	string	Chave única do cartão benefício
payroll_card_status	string	Status do cartão benefício
card_limit	number	Limite total calculado para o cartão

Payload attached_documents

Campo	Tipo	Descrição
document_key	string	Chave única do documento
document_batch_key	string	Chave do lote de documentos
document_type	string	Tipo do documento
document_certifier	string	Certificadora do documento
document_status	string	Status do documento
document_url	string	URL do documento
signature_url	string	URL da assinatura

4. Consulta da reserva do cartão benefício

GET

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

GET

/payroll_card_reservation/social_security/request_identifier_key/[REQUEST-IDENTIFIER-KEY]

Response

Response Body

{
  "request_identifier_key": "550e8400-e29b-41d4-a716-446655440000",
  "payroll_card_reservation_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "payroll_card_reservation_status": "pending_document_generation",
  "card_holder_document_number": "12345678901",
  "identifier_number": "1234567890",
  "reservation_amount": 8000.00,
  "withdrawal": {
    "withdrawal_key": "b2c3d4e5-f6g7-8901-bcde-f23456789012",
    "withdrawal_amount": 5600.00,
    "withdrawal_status": "waiting_signature",
    "contract_number": "PCR000123CES",
    "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": 164.79,
              "due_date": "2025-10-10",
              "installment_number": 1
            },
            {
              "total_amount": 164.79,
              "due_date": "2025-11-10",
              "installment_number": 2
            },
            {
              "total_amount": 164.79,
              "due_date": "2025-12-10",
              "installment_number": 3
            }
          ]
        }
      ]
    }
  },
  "payroll_card": {
    "payroll_card_key": "c3d4e5f6-g7h8-9012-cdef-345678901234",
    "payroll_card_status": "pending_creation",
    "card_limit": 2400.00
  },
  "attached_documents": [
    {
      "document_key": "d4e5f6g7-h8i9-0123-defg-456789012345",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "withdrawal_contract",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": "",
      "signature_url": "",
    },
    {
      "document_key": "f6g7h8i9-j0k1-2345-fghi-678901234567",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "card_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": None,
      "signature_url": None,
    }
  ]
}

5. Webhook de geração de documentos

Após a geração dos documentos (benefit_card_term e withdrawal_operation_term), o cliente receberá um webhook para cada documento.

Atenção

O cliente deve implementar o tratamento deste webhook para capturar as URLs dos documentos e direcionar o beneficiário para a assinatura através da certificadora externa escolhida.

WEBHOOK TYPE

laas.payroll_card_reservation.attached_document.status_change

Webhook Body

{
  "key": "76d41a6e-c515-4e1f-86af-b315ab31b6b4",
  "data": {
    "document_key": "938310ff-ea7c-4661-ac81-2250fefd4b13",
    "document_url": "https://storage.googleapis.com/live-doc-api/documents/withdrawal_operation_term.pdf",
    "document_type": "withdrawal_operation_term",
    "payroll_card_reservation_key": "2c9aa3b0-5e19-433b-b602-f0694873d9d9"
  },
  "status": "generated",
  "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
  "event_datetime": "2025-08-28T01:00:59Z"
}

Webhook Body Details

Campo	Tipo	Descrição
key	string	Chave da reserva do cartão benefício
status	string	Status do documento (generated)
webhook_type	string	Tipo do webhook
event_datetime	string	Data e hora do evento
data	object	Dados do webhook

Payload data

Campo	Tipo	Descrição
payroll_card_reservation_key	string	Chave da reserva do cartão benefício
document_type	string	Tipo do documento
document_url	string	URL do documento para assinatura
document_key	string	Chave única do documento

Enumeradores document_type

Enumerador	Descrição
withdrawal_operation_term	Contrato de CCB de Saque
benefit_card_term	Termos e Condições do Cartão

6. Assinatura externa de documentos

Após receber o webhook de geração dos dois documentos (benefit_card_term e withdrawal_operation_term) para assinatura externa, o cliente deve enviar a confirmação de assinatura através do endpoint abaixo.

Antes de enviar

Antes de confirmar a assinatura, realize o upload dos 5 documentos obrigatórios (selfie, document_identification, document_identification_back, benefit_card_term e withdrawal_operation_term) para obter as respectivas document_keys. Utilize o endpoint de Upload de documentos e, em seguida, informe essas keys no campo "documents" deste request. Consulte: Upload de documentos.

Request

POST

/payroll_card_reservation/social_security/{payroll_card_reservation_key}/signature

Request Body

{
  "documents": [
    { "document_type": "selfie", "document_key": "2c8f2b3d-8c7a-4e3b-9f6a-1234567890ab" },
    { "document_type": "document_identification", "document_key": "b1a2c3d4-e5f6-7890-abcd-ef0123456789" },
    { "document_type": "document_identification_back", "document_key": "0a1b2c3d-4e5f-6789-0abc-def123456789" },
    { "document_type": "benefit_card_term", "document_key": "9f8e7d6c-5b4a-3210-fedc-ba9876543210" }, 
    { "document_type": "withdrawal_operation_term", "document_key": "a05c74eb-542a-4820-8954-eef92ebb383f" }
  ],
  "ip_address": "192.168.1.100",
  "signature_datetime": "2025-01-15T14:30:00Z",
  "similarity_score": 0.95,
  "biometry_analysis_reference": "serpro"
}

Request Body Details

Campo	Tipo	Descrição	Obrigatório
documents	array	Lista dos 5 documentos exigidos	Sim
biometry_analysis_reference	string	Referência da análise biométrica	Sim
signature_datetime	string	Data e hora da assinatura (ISO 8601)	Sim
ip_address	string	Endereço IP de onde foi feita a assinatura	Sim
similarity_score	float	Score de similaridade biométrica	Sim

Enumeradores Biometry Analysis Reference

Enumerador	Descrição
serpro	Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do Detran (Serviço prestado através da Serpro)
tse	Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do TSE
not_found	Deve ser informado quando a biometria facial não for localizada em nenhuma das bases governamentais anteriores (serpro ou tse). Neste caso o similarity_score deve ser null ou o grau de similaridade da selfie com o documento oficial com foto, retornado pelo parceiro.

Item de documents

Campo	Tipo	Descrição	Formatação	Obrigatório
document_type	string	Tipo do documento	Enum: "selfie", "document_identification", "document_identification_back", "benefit_card_term", "withdrawal_operation_term"	Sim
document_key	string	Chave única do documento	UUID v4	Sim

Observações sobre os tipos de documento:

selfie: Foto do beneficiário
document_identification: Frente do documento de identificação
document_identification_back: Verso do documento de identificação
benefit_card_term: Termos e condições do cartão assinado
withdrawal_operation_term: Termo da operação de saque assinado

QI Sign

A QI Tech oferece o serviço de assinatura que atende ao determinado pela IN 138. Com biometria facial e envio de documentos.

Para receber uma cotação consulte nosso time comercial:

comercial@qitech.com.br ou (11) 2339-4763

Response

STATUS

200 (OK)

Response Body

{
  "payroll_card_reservation_key": "d4e5f6g7-h8i9-0123-defg-456789012345",
  "payroll_card_reservation_status": "pending_onboarding",
  "attached_documents": [
    {
      "document_key": "0b6c9bb9-0bc1-4fd2-9aab-3ccf5c8bc69d",
      "document_type": "withdrawal_operation_term",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/withdrawal_operation_term.pdf",
      "document_status": "signed",
      "document_batch_key": "ccc42bc6-efbc-4e8f-a7da-fb6cb77e4146",
      "signature_url": "https://storage.googleapis.com/live-doc-api/documents/withdrawal_operation_term_signed.pdf",
    },
    {
      "document_key": "f974bb60-ff4c-4027-9d88-399470586691",
      "document_type": "benefit_card_term",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/benefit_card_term.pdf",
      "document_status": "signed",
      "document_batch_key": "ccc42bc6-efbc-4e8f-a7da-fb6cb77e4146",
      "signature_url": "https://storage.googleapis.com/live-doc-api/documents/benefit_card_term_signed.pdf",
    },
    {
      "document_key": "2c8f2b3d-8c7a-4e3b-9f6a-1234567890ab",
      "document_type": "selfie",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/selfie.pdf",
      "document_status": "generated"
    },
    {
      "document_key": "b1a2c3d4-e5f6-7890-abcd-ef0123456789",
      "document_type": "document_identification",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/document_identification.pdf",
      "document_status": "generated"
    },
    {
      "document_key": "0a1b2c3d-4e5f-6789-0abc-def123456789",
      "document_type": "document_identification_back",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/document_identification_back.pdf",
      "document_status": "generated"
    }
  ]
}

Response Body Details

Campo	Tipo	Descrição
payroll_card_reservation_key	string	Chave da reserva do cartão benefício
payroll_card_reservation_status	string	Status da reserva (pending_onboarding)
attached_documents	array	Lista de documentos e seus status

Informação

Após a confirmação da assinatura dos dois documentos, o status do cartão benefício será alterado para "pending_onboarding", indicando que a operação está aguardando o processo de onboarding do cartão.

Erros comuns

404 - Document Not Found

{
  "title": "Document Not Found",
  "description": "Document selfie not found",
  "translation": "Documento selfie não encontrado"
}

Explicação: Este erro ocorre quando a document_key informada no request não foi encontrada no sistema. Verifique se a document_key foi obtida corretamente através do endpoint de Upload de documentos

7. Webhook de assinatura via Qi Sign

Quando a assinatura dos documentos é feita via Qi Sign após a criação da operação de saque, o cliente receberá um webhook confirmando a assinatura e informando a mudança de status para "pending_onboarding".

WEBHOOK TYPE

payroll_card.qisign.signature_completed

O webhook será enviado quando a assinatura via Qi Sign for concluída:

Webhook Body

{
    "key": "<Payroll Card Reservation Key>",
    "status": "signature_completed",
    "webhook_type": "payroll_card.qisign.signature_completed",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "payroll_card_reservation_key": "<Payroll Card Reservation Key>",
        "payroll_card_status": "pending_onboarding",
        "documents": [
            {
                "document_type": "withdrawal_contract",
                "document_name": "Contrato de CCB de Saque",
                "document_key": "0b6c9bb9-0bc1-4fd2-9aab-3ccf5c8bc69d",
                "document_certifier": "qi_sign",
                "document_status": "signed"
            },
            {
                "document_type": "card_term",
                "document_name": "Termos e Condições do Cartão",
                "document_key": "f974bb60-ff4c-4027-9d88-399470586691",
                "document_certifier": "qi_sign",
                "document_status": "signed"
            }
        ]
    }
}

Webhook Body Details

Campo	Tipo	Descrição	Formatação
key	string	Chave da reserva do cartão benefício	UUID v4
status	string	Status do webhook (signature_completed)	Enum: "signature_completed"
webhook_type	string	Tipo do webhook	String
event_datetime	string	Data e hora do evento	ISO 8601 (YYYY-MM-DDTHH:mm:ssZ)
data	object	Dados do webhook	-

Payload data

Campo	Tipo	Descrição	Formatação
payroll_card_reservation_key	string	Chave da reserva do cartão benefício	UUID v4
payroll_card_reservation_status	string	Status da reserva so cartão benefício (pending_onboarding)	Enum: "pending_onboarding"
documents	array	Chaves dos documentos assinados	-
signature_details	object	Detalhes da assinatura via Qi Sign	-

Campo	Tipo	Descrição	Formatação
document_type	string	Tipo do documento assinado	String
document_name	string	Nome do documento assinado	String
document_key	string	Chave única do documento assinado	UUID v4
document_certifier	string	Certificadora responsável pela assinatura	String
document_status	string	Status do documento após assinatura	Enum: "signed"

Informação

Este webhook é enviado automaticamente quando a assinatura via Qi Sign é concluída, confirmando que todos os documentos foram assinados e a operação está pronta para o processo de onboarding do cartão.

8. Webhook de falha no onboarding/KYC

Quando o processo de onboarding ou KYC (Know Your Customer) falha, o cliente receberá um webhook informando a rejeição da operação e o motivo da falha.

WEBHOOK TYPE

payroll_card.onboarding.rejected

O webhook será enviado quando o onboarding ou KYC for rejeitado:

Webhook Body

{
    "key": "<Payroll Card Reservation Key>",
    "status": "rejected",
    "webhook_type": "payroll_card.onboarding.rejected",
    "event_datetime": "2025-01-15T16:45:00Z",
    "data": {
        "payroll_card_reservation_key": "<Payroll Card Reservation Key>",
        "payroll_card_reservation_status": "rejected",
        "rejected_reason": "kyc_failed",
        "rejection_details": {
            "error_code": "KYC001",
            "description": "Documento de identificação não legível",
            "translation": "Documento de identificação não legível"
        }
    }
}

Webhook Body Details

Campo	Tipo	Descrição	Formatação
key	string	Chave da reserva do cartão benefício	UUID v4
status	string	Status do webhook (rejected)	Enum: "rejected"
webhook_type	string	Tipo do webhook	String
event_datetime	string	Data e hora do evento	ISO 8601 (YYYY-MM-DDTHH:mm:ssZ)
data	object	Dados do webhook	-

Payload data

Campo	Tipo	Descrição	Formatação
payroll_card_reservation_key	string	Chave da reserva do cartão benefício	UUID v4
payroll_card_reservation_status	string	Status da reserva do cartão benefício	Enum: "rejected"
rejected_reason	string	Motivo da rejeição	Enum: "kyc_failed", "onboarding_failed", "document_invalid", "identity_verification_failed", "card_issuance_failed"
rejection_details	object	Detalhes da rejeição	-

Payload rejection_details

Campo	Tipo	Descrição	Formatação
error_code	string	Código do erro	String alfanumérica
description	string	Descrição do erro	String
translation	string	Tradução da descrição do erro	String

9. Webhook de desembolso do saque

Quando o KYC é aprovado e a operação de saque é desembolsada com sucesso, o cliente receberá um webhook confirmando o desembolso da operação.

WEBHOOK TYPE

payroll_card.disbursement.completed

O webhook será enviado quando o desembolso for realizado com sucesso:

Webhook Body

{
    "key": "871059bd-4014-41ad-82b4-28275ff0e67b",
    "data": {
        "installments": [{
            "due_date": "2022-09-29",
            "qr_code_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
            "qr_code_url": "https://qitech.com.br/",
            "bank_slip_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
            "digitable_line": "32990001031000699920446000000201991230000019896"
        }, {
            "due_date": "2022-10-31",
            "qr_code_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
            "qr_code_url": "https://qitech.com.br/",
            "bank_slip_key": "243f9441-872a-4d64-886c-2f9724c36f2e",
            "digitable_line": "32990001031000699920447000000209191550000019896"
        }, {
            "due_date": "2022-11-29",
            "qr_code_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
            "qr_code_url": "https://qitech.com.br/",
            "bank_slip_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
            "digitable_line": "32990001031000699920448000000207891840000019896"
        }, {
            "due_date": "2022-12-29",
            "qr_code_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/cf7d2d2e-003a-4296-9daf-350864d282245204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63047335",
            "bank_slip_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
            "digitable_line": "32990001031000699920449000000205892140000019896"
        }, {
            "due_date": "2023-01-30",
            "qr_code_key": "e809ffca-ac2f-4a51-9f4f-df7ffc4de8e3",
            "qr_code_url": "https://qitech.com.br/",
            "bank_slip_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
            "digitable_line": "32990001031000699920450000000203792460000019892"
        }],
        "ted_receipt_list": [{
            "fee": 0,
            "url": "https://qitech.com.br/",
            "amount": 500,
            "origin": {
                "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
                "type": "payment_account",
                "branch": "0001",
                "document": "0000000000000",
                "bank_code": "000",
                "account_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
                "branch_digit": null,
                "account_digit": "5",
                "account_branch": "0001",
                "account_number": "00002"
            },
            "timestamp": "2022-09-28T13:00:47",
            "description": "DESCRIPTION",
            "destination": {
                "name": "QI TECH",
                "type": "checking_account",
                "branch": "0000",
                "purpose": "Crédito PIX em Conta",
                "document": "000000000000000",
                "bank_ispb": "00000000",
                "branch_digit": null,
                "account_digit": "0",
                "account_number": "00000000"
            },
            "end_to_end_id": null,
            "transaction_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
            "origin_transaction_key": null
        }],
        "requester_identifier_key": "57f8e1ce-1080-4d0d-a195-89709b961561"
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2022-09-28 13:01:23"
}

Webhook Body Details

Campo	Tipo	Descrição	Formatação
key	string	Chave da reserva do cartão benefício	UUID v4
status	string	Status do webhook (disbursed)	Enum: "disbursed"
webhook_type	string	Tipo do webhook	String
event_datetime	string	Data e hora do evento	ISO 8601 (YYYY-MM-DDTHH:mm:ssZ)
data	object	Dados do webhook	-

Payload data

Campo	Tipo	Descrição	Formatação
installments	array	Lista de parcelas da CCB de saque	-
ted_receipt_list	array	Lista de comprovantes de TED de desembolso	-
requester_identifier_key	string	Chave de identificação do solicitante	UUID v4

Payload installments

Campo	Tipo	Descrição	Formatação
due_date	string	Data de vencimento da parcela	YYYY-MM-DD
qr_code_key	string	Chave do QR Code	UUID v4
qr_code_url	string	URL do QR Code	URL válida
bank_slip_key	string	Chave do boleto	UUID v4
digitable_line	string	Linha digitável do boleto	String numérica

Payload ted_receipt_list

Campo	Tipo	Descrição	Formatação
fee	number	Taxa da TED	Decimal
url	string	URL do comprovante	URL válida
amount	number	Valor da TED	Decimal
origin	object	Dados da conta de origem	-
timestamp	string	Data e hora da TED	ISO 8601 (YYYY-MM-DDTHH:mm:ss)
description	string	Descrição da TED	String
destination	object	Dados da conta de destino	-
end_to_end_id	string	ID end-to-end da transação	String alfanumérica
transaction_key	string	Chave da transação	UUID v4
origin_transaction_key	string	Chave da transação de origem	UUID v4

Sucesso

O webhook de desembolso confirmado indica que a operação de saque foi desembolsada com sucesso através do método de transferência informado.

10. Webhook de criação da wallet e cartão

Quando a wallet e o cartão benefício são criados com sucesso, o cliente receberá um webhook confirmando a emissão do cartão.

WEBHOOK TYPE

payroll_card.card_issued

O webhook será enviado quando a wallet e o cartão forem criados com sucesso:

Webhook Body

{
    "key": "<Payroll Card Reservation Key>",
    "webhook_type": "payroll_card.card_issued",
    "event_datetime": "2025-01-15T18:30:00Z",
    "data": {
        "payroll_card_reservation_key": "<Payroll Card Reservation Key>",
        "card_holder": {
            "name": "Nome devedor",
            "document_number": "14471835092"
        },
        "payroll_card_status": "card_issued",
        "wallet_key": "550e8400-e29b-41d4-a716-446655440000",
        "card_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "payroll_card": {
            "card_limit": 773.18,
            "card_number": "4111111111111111",
            "card_status": "active",
            "activation_date": "2025-01-15T18:30:00Z"
        }
    }
}

Webhook Body Details

Campo	Tipo	Descrição	Formatação
key	string	Chave da reserva do cartão benefício	UUID v4
webhook_type	string	Tipo do webhook	String
event_datetime	string	Data e hora do evento	ISO 8601 (YYYY-MM-DDTHH:mm:ssZ)
data	object	Dados do webhook	-

Payload data

Campo	Tipo	Descrição	Formatação
payroll_card_reservation_key	string	Chave da reserva do cartão benefício	UUID v4
card_holder	object	Dados do portador do cartão	-
card_holder.name	string	Nome do portador	String
card_holder.document_number	string	CPF do portador	11 dígitos numéricos
payroll_card_status	string	Status do cartão benefício (card_issued)	Enum: "card_issued"
wallet_key	string	Chave única da wallet criada (UUID4)	UUID v4
card_key	string	Chave única do cartão criado (UUID4)	UUID v4
payroll_card	object	Dados do cartão benefício criado	-

Payload payroll_card

Campo	Tipo	Descrição	Formatação
card_limit	number	Limite total do cartão	Decimal
card_number	string	Número do cartão (mascarado)	String
card_status	string	Status do cartão (active)	Enum: "active"
activation_date	string	Data de ativação do cartão	ISO 8601 (YYYY-MM-DDTHH:mm:ssZ)

Sucesso

Este webhook é enviado após o desembolso bem-sucedido e a conclusão do processo de criação da wallet e emissão do cartão.

Informação

Após a criação da wallet e emissão do cartão, será enviado um email de notificação de desembolso para o beneficiário e o cartão físico será despachado para o endereço cadastrado.

Máquinas de Status

Payroll Card Reservation

A entidade Payroll Card Reservation possui os seguintes status e transições:

Descrição dos Status

Status	Descrição
`pending_document_generation`	Aguardando geração dos documentos para assinatura
`pending_onboarding`	Aguardando processo de onboarding e KYC
`rejected`	Operação rejeitada (falha no onboarding/KYC)
`pending_collateral_reservation`	Aguardando reserva do colateral
`pending_withdrawal_disbursement`	Aguardando desembolso da operação de saque
`pending_card_issuance`	Aguardando criação da wallet e emissão do cartão
`card_issued`	Cartão criado e ativo
`canceled`	Operação cancelada

Withdrawal

A entidade Withdrawal possui os seguintes status e transições:

Descrição dos Status

Status	Descrição
`pending_signature`	Aguardando assinatura dos termos
`pending_disbursement`	Aguardando desembolso da operação de saque
`opened`	Desembolso realizado e operação ativa
`canceled`	Operação cancelada

Manual Cartão Benefício

1. Consulta de elegibilidade do beneficiário​

Request​

Response​

2. Simulação de saque e limite do cartão​

Request​

Payload financial​

Payload withdrawal​

Payload collateral​

Response​

Payload withdrawal.withdrawal_data​

Payload disbursement_options​

Payload prefixed_interest_rate​

Payload installments​

3. Criação da operação de saque e geração do termo​

Request​

Payload card_holder​

Payload phone​

Payload address​

Payload document_identification​

Payload withdrawal​

Payload disbursement_bank_accounts​

Payload financial​

Payload fine_configuration​

Payload collateral​

Payload credit_agent​

Payload related_parties​

Response​

Payload withdrawal​

Payload withdrawal_data​

Payload disbursement_options​

Payload prefixed_interest_rate​

Payload installments​

Payload payroll_card​

Payload attached_documents​

4. Consulta da reserva do cartão benefício​

Response​

5. Webhook de geração de documentos​

Payload data​

Enumeradores document_type​

6. Assinatura externa de documentos​

Request​

Enumeradores Biometry Analysis Reference​

Item de documents​

Response​

Erros comuns​

7. Webhook de assinatura via Qi Sign​

Payload data​

8. Webhook de falha no onboarding/KYC​

Payload data​

Payload rejection_details​

9. Webhook de desembolso do saque​

Payload data​

Payload installments​

Payload ted_receipt_list​

10. Webhook de criação da wallet e cartão​

Payload data​

Payload payroll_card​

Máquinas de Status​

Payroll Card Reservation​

Descrição dos Status​

Withdrawal​

Descrição dos Status​

1. Consulta de elegibilidade do beneficiário

Request

Response

2. Simulação de saque e limite do cartão

Request

Payload financial

Payload withdrawal

Payload collateral

Response

Payload withdrawal.withdrawal_data

Payload disbursement_options

Payload prefixed_interest_rate

Payload installments

3. Criação da operação de saque e geração do termo

Request

Payload card_holder

Payload phone

Payload address

Payload document_identification

Payload withdrawal

Payload disbursement_bank_accounts

Payload financial

Payload fine_configuration

Payload collateral

Payload credit_agent

Payload related_parties

Response

Payload withdrawal

Payload withdrawal_data

Payload disbursement_options

Payload prefixed_interest_rate

Payload installments

Payload payroll_card

Payload attached_documents

4. Consulta da reserva do cartão benefício

Response

5. Webhook de geração de documentos

Payload data

Enumeradores document_type

6. Assinatura externa de documentos

Request

Enumeradores Biometry Analysis Reference

Item de documents

Response

Erros comuns

7. Webhook de assinatura via Qi Sign

Payload data

8. Webhook de falha no onboarding/KYC

Payload data

Payload rejection_details

9. Webhook de desembolso do saque

Payload data

Payload installments

Payload ted_receipt_list

10. Webhook de criação da wallet e cartão

Payload data

Payload payroll_card

Máquinas de Status

Payroll Card Reservation

Descrição dos Status

Withdrawal

Descrição dos Status