Manual Cartão Consignado: Visão Geral

O cartão consignado é um cartão de crédito cujo limite é garantido por uma margem consignável — uma parcela mensal descontada diretamente da folha de pagamento ou do benefício do titular. Na contratação, parte do limite é liberada como saque em conta, e o restante fica disponível como limite rotativo do cartão.

API em desenvolvimento

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

O que a QI Tech entrega

Uma única integração cobre a operação inteira: a simulação das condições, a emissão da CCB de saque, o onboarding e a assinatura digital dos termos, a averbação da margem junto ao órgão consignante, o desembolso e a emissão do cartão físico.

Produto	product_type	O que é
Cartão Benefício	benefit_card	Cartão de benefício com limite consignado
Cartão Consignado	payroll_card	Cartão de crédito consignado

A jornada de uma contratação

Do primeiro contato até o cartão na mão do titular:

1. Elegibilidade — verifica se o CPF pode contratar. Síncrono. Ver Emissão.
2. Simulação — calcula limite total, valor de saque e parcelas a partir da margem e das condições financeiras. Nada é criado ainda.
3. Criação da reserva — cria a operação, gera os termos e devolve a payroll_card_reservation_key, a chave que identifica a contratação daqui em diante.
4. Onboarding e assinatura — o titular passa por KYC, assina os termos e envia o vídeo de confirmação. Ver Documentos e Assinatura.
5. Averbação da margem — a QI Tech reserva a margem junto ao órgão consignante. É a etapa que depende da fonte de consignação e a que pode falhar por margem insuficiente.
6. Desembolso e emissão — o saque é desembolsado na conta informada e o cartão é emitido e enviado. Ver Gestão de Endereço.

Cada transição emite um webhook. A máquina de status completa está em Acompanhamento; as notificações, em Webhooks.

Fontes de consignação

O mesmo produto atende mais de uma folha de pagamento. A fonte de consignação é o primeiro segmento da rota, e o produto é um campo do corpo da requisição:

POST /payroll_card_reservation/{collateral_type}
{
  "product_type": "benefit_card",
  "collateral": { ... no formato da fonte informada na rota ... }
}

Fonte	Valor na rota	Quem atende	Regras do produto
INSS	social_security	Aposentados e pensionistas do INSS	INSS
Consignado Público	public_payroll	Servidores públicos estaduais e municipais	Consignado Público

A combinação de fonte e produto resolve o tipo de cartão (payroll_card_type), que é o que a API devolve nas respostas e o que carrega a configuração comercial: tetos de parcelas e de taxa, faixa etária elegível e multiplicador de limite. Uma combinação não contratada é recusada com 400 PCR000004.

Entre as fontes, variam apenas três coisas — o segmento da rota, a seção collateral e a entrada financeira aceita (salary_amount ou available_margin). O restante da jornada é idêntico.

Exemplos e Playground

Os exemplos executáveis deste manual usam social_security na rota, por ser a fonte disponível hoje.

Conteúdo desta seção

1. Emissão — elegibilidade, simulação, criação da operação e envio de documentos adicionais.
2. Acompanhamento — consulta da reserva, consulta por CPF do titular e máquina de status.
3. Webhooks — notificações de mudança de status da reserva, do saque e do cartão.
4. Documentos e Assinatura — geração, assinatura e reenvio dos termos.
5. Gestão de Endereço — atualização do endereço de entrega do cartão.
6. Changelog — mudanças de contrato relevantes para quem já integra.

Glossário

Termo	Significado
Margem consignável	Valor mensal que pode ser comprometido com a operação, descontado direto da folha ou do benefício. É a base do limite do cartão.
Averbação	Reserva da margem junto ao órgão consignante, o que torna o desconto efetivo.
Reserva (payroll_card_reservation)	A entidade que acompanha a contratação, da criação até a emissão do cartão.
Saque (withdrawal)	A parte do limite liberada em conta na contratação, formalizada em uma CCB.
Fonte de consignação (collateral_type)	A folha que garante a operação — social_security (INSS) ou public_payroll (servidores públicos estaduais e municipais). É o primeiro segmento da rota.
Produto (product_type)	O cartão contratado — benefit_card ou payroll_card. É um campo do corpo da requisição.
Tipo de cartão (payroll_card_type)	A combinação de fonte e produto, por exemplo social_security_benefit_card. Carrega a configuração comercial e aparece nas respostas.