Skip to main content

Manual Consignado Privado - Portabilidade: Acompanhamento da Operação

Status da Proposta de Portabilidade

Os estados da Proposta de Portabilidade refletem as etapas envolvidas no processo de portabilidade de crédito dentro do CTC (Central de Transferência de Crédito) da Núclea. Segue abaixo a descrição do fluxo e do significado de cada status envolvido em uma Proposta de Portabilidade, desde sua digitação até sua liquidação.

pending_response

Status da proposta após realização da digitação. Neste status a proposta foi recebida com sucesso pela QI e enviada para o CTC.

rejected

Caso a digitação da proposta seja rejeitada pelo CTC, será enviado um webhook com o motivo da rejeição:

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal
  • STATUS
    rejected
webhook.json
{
"webhook_type": "credit_transfer.proposal",
"proposal_key": "<PROPOSAL-KEY>",
"proposal_status": "rejected",
"event_datetime": "2022-11-24T15:42:12",
"data": {
"error": {
"code": "ECTC0023",
"reason": "Contrato com portabilidade em andamento"
}
}
}

rejected reasons

Caso a digitação da proposta seja rejeitada pelo CTC, será enviado um webhook com o motivo da rejeição:

reasondescriptionexternal_code
portability_in_progressContrato com portabilidade em andamentoECTC0023
portability_finishedPortabilidade já finalizada para o contrato informadoECTC0028
portability_in_expiration_progressPortabilidade não permitida. Contrato com portabilidade em situação de "Decurso de prazo" por não efetivação da portabilidadeECTC0085
unexpected_errorErro inesperadoECTC9999
portability_payment_rejectedPagamento de portabilidade rejeitado.
divergent_due_balanceSaldo devedor final deve ser menor que saldo devedor devolvido pela Núclea.

pending_acceptance

Status da Proposta após envio/aceite pelo CTC. A Proposta, neste momento, está aguardando resposta de saldo devedor pelo banco credor original. Neste momento é enviado um webhook com o número da Portabilidade no CTC:

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal
  • STATUS
    pending_acceptance
webhook.json
{
"webhook_type": "credit_transfer.proposal",
"proposal_key": "<PROPOSAL-KEY>",
"proposal_status": "pending_acceptance",
"event_datetime": "2022-11-24T15:42:12",
"data": {
"portability_number": "202211230000246536429",
"inclusion_date": "2022-11-24",
"due_balance_expected_return_date": "2022-12-01"
}
}
info

O “portability_number“ é o Número da Portabilidade dentro do CTC, e é o número utilizado pela instituição proponente e instituição credora original para localizar a Proposta de Portabilidade.

Assim que o banco credor original responder à solicitação de portabilidade, será enviado um webhook com a resposta do valor do saldo devedor no caso da não retenção, e com a informação de “retido”, no caso da retenção:

accepted

Status da Proposta quando o banco credor original retorna o saldo devedor e não retem o crédito. Será enviado um webhook com a informação do saldo devedor. O banco credor original tem até 5 d.u. após a recepção da Proposta de Portabilidade, para envio da resposta com a informação do saldo devedor da operação.

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal
  • STATUS
    accepted
webhook.json
{
"webhook_type": "credit_transfer.proposal",
"proposal_key": "<PROPOSAL-KEY>",
"proposal_status": "accepted",
"event_datetime": "2022-11-24T15:42:12",
"data": {
"final_due_balance": 1000,
"portability_number": "202211230000246536429",
"original_contract": {
"origin_contract_number": "5584745",
"origin_ispb_number": "60746948",
"origin_document_number": "90406718261",
"origin_operation_type": "0202",
"installment_face_value": 1000,
"total_iof": 1,
"first_due_date": "2021-05-31",
"last_due_date": "2022-05-31",
"interest": 1,
"cet": 1,
"installment_number": 12,
"amortization": 1,
"final_due_balance": 1000,
"final_due_date": "2021-08-31",
"contract_date": "2021-04-31"
}
}
}

Com a informação do saldo devedor retornado pela instituição credora original, o parceiro tomará a decisão se seguir ou não com a Portabilidade.

info

Horário limite para envio do saldo devedor pela instituição credora original é às 10:00.

Após o recebimento do saldo devedor, caso o Parceiro decida seguir com a Proposta Portabilidade, ele deve realizar a seguinte chamada:

ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY
MÉTODO
PATCH
Testar no Playground

Requisição

request.json
{
"status": "accepted_by_requester"
}
Atenção

Para propostas que envolvam troco após o refinanciamento, é necessário que o valor do troco calculado de acordo com as novas condições do contrato após o retorno do saldo devedor seja de pelo menos 5% da diferença entre a soma de todas as parcelas do refinanciamento subtraida da soma de todas as parcelas da portabilidade. Caso contrário, a requisição receberá o seguinte erro:

STATUS
400
Response Body
{
"code": "CT000118",
"title": "Bad Request",
"description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.",
"translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00."
}

O Parceiro pode adicionar dados de novo valor de parcela ou nova taxa nessa chamada, caso queira alterá-los:

ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY
MÉTODO
PATCH

Requisição

request.json
{
"status": "accepted_by_requester",
"financial": {
"installment_face_value": 100
}
}
ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY
MÉTODO
PATCH

Requisição

request.json
{
"status": "accepted_by_requester",
"financial": {
"monthly_interest_rate": 0.01
}
}
Campos adicionais opcionais

Além dos campos status e financial, o endpoint de aceite da proposta também aceita os seguintes campos opcionais:

  • borrower.document_identification_type (string ou null): Tipo do documento de identificação
  • borrower.document_identification_number (string, máx. 16 caracteres): Número do documento de identificação
  • borrower.gender (string ou null): Gênero do tomador. Valores aceitos: "male", "female" ou null
Atenção!

Caso o valor da parcela seja maior que valor total disponível (valor da parcela do contrato de origem + margem consignável total disponível), será retornado o seguinte erro:

{
"code": "SSC000059",
"title": "Reservation amount greater than available total balance",
"description": "The installment face value: 54.4 is greater than the available total balance (origin installment face value + available total balance):30.4. Available total balance: -20.0.",
"translation": "O valor da parcela: 54.4 é maior que o valor total disponível (valor da parcela do contrato de origem + margem total disponível) : 30.4. Margem total diponível: -20.0."
}

Ao receber esta crítica, é possível que uma nova chamada seja feita, alterando o valor da parcela para que ela se ajuste ao valor total disponível.

Se o ajuste no valor da parcela não for feito até o horário limite para aceite do saldo devedor, será necessária uma nova digitação de proposta.

Caso o Parceiro decida por não prosseguir com a Proposta de Portabilidade, ele deve, obrigatoriamente realizar a seguinte chamada para informar a desistência da Portabilidade:

ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY
MÉTODO
DELETE
Testar no Playground

Após o envio do cancelamento da Proposta de Portabilidade ao CTC, será enviado um webhook de Proposta Cancelada:

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal
  • STATUS
    canceled
webhook.json
{
"webhook_type": "credit_transfer.proposal",
"proposal_status": "canceled",
"proposal_key": "<PROPOSAL-KEY>",
"event_datetime": "2022-11-24T15:42:12"
}
info

O horário limite para aceite do saldo devedor é 16:30. Não é possível retomar uma Proposta com status “canceled”. Caso a Proposta esteja com este status, será necessária a realização de uma nova digitação.

retained

Status da Proposta quando o banco credor original retem o crédito, será enviado o webhook com a informação de retenção. O banco credor original do crédito tem até 2 d.u. após a recepção da Proposta de Portabilidade, para envio da resposta de retenção do crédito.

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal
  • STATUS
    retained
webhook.json
{
"webhook_type": "credit_transfer.proposal",
"proposal_key": "<PROPOSAL-KEY>",
"proposal_status": "retained",
"event_datetime": "2022-11-24T15:42:12",
"data": {
"retained_reason": {
"reason": "issuer_retention",
"description": "Retenção do Cliente"
}
}
}

Detalhamento de campos no webhook de proposal

CampoDescriçãoValores
reasonlista dos motivos de retenção de uma PropostaEnumeradores

accepted_by_requester

Após aprovada pelo parceiro, a Proposta segue o fluxo interno da QI para liquidação.

settlement_sent

Após conclusão do fluxo interno da QI para liquidação da Proposta de Portabilidade o recurso para pagamento do saldo devedor é enviado ao credor original disparando o seguinte webhook para o Parceiro:

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal
  • STATUS
    settlement_sent
webhook.json
{
"webhook_type": "credit_transfer.proposal",
"proposal_key": "<PROPOSAL KEY>",
"proposal_status": "settlement_sent",
"event_datetime": "2022-11-24T15:42:12",
"data": {
"receipt": {
"amount": 1000,
"timestamp": "2022-09-14 11:55:31",
"description": "237 0001 1000093 1000093-3 59588111000103 - BCO BRADESCO S.A.",
"ted_receipt_document_key": "a34e84a2-1628-4f23-8c11-2b2f4656ced1",
"ted_receipt_url": "https://qitech.com.br/",
"transaction_key": "ed3e84a2-1628-4f23-8c11-2b2f4656cedf",
"origin": {
"account_key": "ed3e84a2-1628-4f23-8c11-2b2f4656cedf",
"bank_code": "329",
"branch": "0001",
"branch_digit": null,
"account_number": "1000361",
"account_digit": "3",
"type": "checking_account",
"name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"document": "32402502000135"
},
"destination": {
"bank_code": "237",
"branch": "0001",
"branch_digit": null,
"account_number": "1000093",
"account_digit": "3",
"type": "checking_account",
"name": "BCO BRADESCO S.A.",
"document": "59588111000103",
"purpose": "Saída Liquidação de Portabilidade"
}
}
}
}

Neste momento será iniciada averbação da Operação de Portabilidade na folha do empregador. O processo de averbação acontecerá em paralelo aos itens seguintes (itens 7.5., 7.5.1. e 7.5.2.)

pending_settlement_confirmation

Após a confirmação do envio dos recursos para pagamento do saldo devedor, é aguardada a confirmação da quitação do contrato por parte da Instituição Credora Original. Nesta etapa o Parceiro receberá o seguinte webhook:

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal
  • STATUS
    pending_settlement_confirmation
webhook.json
{
"webhook_type": "credit_transfer.proposal",
"proposal_key": "<PROPOSAL-KEY>",
"proposal_status": "pending_settlement_confirmation",
"event_datetime": "2022-11-24T15:42:12"
}
info

A confirmação da quitação do contrato é encaminhada pela Instituição Credora Original ao CTC e posteriormente encaminhado pelo CTC à QI.

O SLA para confirmação da quitação da Portabilidade é de 2 d.u. contados a partir do envio dos recursos para pagamento do saldo devedor do contrato original.

Assim que a QI receber do CTC a confirmação da quitação do Contrato Original, a Proposta constará como paga e a Portabilidade estará finalizada.

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal
  • STATUS
    paid
webhook.json
{
"webhook_type": "credit_transfer.proposal",
"proposal_key": "<PROPOSAL-KEY>",
"proposal_status": "paid",
"event_datetime": "2022-11-24T15:42:12"
}

Nesta etapa, caso a averbação da Operação de Portabilidade já esteja concluída, a Operação de Refinanciamento (Troco), poderá ser iniciada (fluxo descrito no item 7).

A notificação sobre a averbação da Operação de Portabilidade será enviada através do seguinte webhook:

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal.collateral
webhook.json
{
"webhook_type": "credit_transfer.proposal.collateral",
"proposal_key": "<PROPOSAL-KEY>",
"event_datetime": "2022-11-24T15:42:12",
"data": {
"credit_operation_type": "portability",
"credit_operation_key": "<CREDIT-OPERATION-KEY>",
"collateral_type": "private_payroll",
"collateral_constituted": true,
"collateral_data": {
"reservation_method": "portability"
}
}
}

data.collateral_data.reservation_method: [portability, new_credit ]

rejected

Caso o banco credor original rejeite a quitação do contrato, o recurso enviado para quitação do saldo devedor do contrato original será devolvido, e a proposta será finalizada. O parceiro receberá o webhook de “rejected”.

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal
  • STATUS
    rejected
webhook.json
{
"webhook_type": "credit_transfer.proposal",
"proposal_key": "<PROPOSAL-KEY>",
"proposal_status": "rejected",
"event_datetime": "2022-11-24T15:42:12",
"data": {
"error": {
"code": "QCTC0001",
"reason": "Pagamento de portabilidade rejeitado."
}
}
}

Caso nesta etapa a Operação de Portabilidada já esteja averbada na folha do empregador, será realizada a desaverbação da margem.

info

Não é possível retomar uma Proposta com status “rejected”. É sempre necessário realizar uma nova digitação.


Status da Operação de Refinanciamento (Troco)

No momento em que a Operação de Portabilidade é paga, o Parceiro pode optar por seguir com a Operação de Refinanciamento (Troco) ou não.

Enumeradores credit_operation_status

EnumeradorDescrição
waiting_signatureOperação aguardando assinatura
signedOperação assinada
issuedOperação emitida
disbursedOperação desembolsada
settledOperação liquidada
canceledOperação cancelada
canceled_permanentlyOperação cancelada permanentemente

Para prosseguir com o Refinanciamento (Troco), o Parceiro deve realizar a seguinte chamada passando os campos 'Financial' e 'Disbursement Bank Accounts':

*Adicionalmente, pode-se passar o campo 'purchaser_document_number' para alterar o cessionário da operação.

ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY/refinancing_credit_operation/acceptance
MÉTODO
POST
Testar no Playground

Requisição

request.json
{
"financial": {
"installment_face_value": 379.87,
"monthly_interest_rate": 0.0166,
"number_of_installments": 84,
"limit_days_to_disburse": 7,
"disbursement_date": "2024-07-02",
"rebates": [
{
"rebate_bank_account": {
"bank_code": "329",
"account_digit": "9",
"document_number": "18533555000164",
"name": "Teste Ltda",
"account_number": "4290002",
"branch_number": "0001"
},
"amount_type": "percentage",
"fee_type": "spread",
"amount": 9.5
},
{
"amount": 20,
"rebate_bank_account": {
"name": "Teste Ltda",
"document_number": "18533555000164",
"account_digit": "0",
"account_number": "4290001",
"branch_number": "0001",
"bank_code": "329"
},
"amount_type": "percentage",
"fee_type": "insurance_premium"
}
]
},
"disbursement_bank_accounts": [
{
"document_number": "92093764000197",
"branch_number": "0001",
"name": "TESTE LTDA",
"percentage_receivable": 100,
"account_number": "120012",
"account_digit": "3",
"bank_code": "329"
}
],
"purchaser_document_number": "28534595027164"
}

Resposta

response.json
{
"credit_operation_key": "<CREDIT-OPERATION-KEY>",
"contract_number": "00000002",
"document_key": "<DOCUMENT-KEY da CCB de Refinanciamento>",
"document_url": "<URL da CCB de Refinanciamento>",
"credit_operation_status": "issued",
"fine_configuration": {
"contract_fine_rate": 0.02,
"interest_base": "calendar_days",
"monthly_rate": 0.01
},
"disbursement_options": [
{
"installments": [
{
"additional_costs": [],
"bank_slip_key": null,
"business_due_date": "2021-08-09",
"calendar_days": 53,
"digitable_line": null,
"due_date": "2021-08-08",
"due_interest": 0,
"due_principal": 997.87,
"fine_amount": null,
"has_interest": true,
"installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
"installment_number": 1,
"installment_status": "created",
"installment_type": "principal",
"paid_amount": 0,
"paid_at": null,
"post_fixed_amount": 0,
"pre_fixed_amount": 54.84865004983954,
"principal_amortization_amount": 306.98134995016045,
"total_amount": 361.83,
"workdays": 37
},
{
"additional_costs": [],
"bank_slip_key": null,
"business_due_date": "2021-09-08",
"calendar_days": 31,
"digitable_line": null,
"due_date": "2021-09-08",
"due_interest": 0,
"due_principal": 690.8886500498395,
"fine_amount": null,
"has_interest": true,
"installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1",
"installment_number": 2,
"installment_status": "created",
"installment_type": "principal",
"paid_amount": 0,
"paid_at": null,
"post_fixed_amount": 0,
"pre_fixed_amount": 21.964874249804833,
"principal_amortization_amount": 339.86512575019515,
"tax_amount": 0,
"total_amount": 361.83,
"workdays": 22
}
],
"prefixed_interest_rate": {
"annual_rate": 0.44556431,
"daily_rate": 0.00564312,
"monthly_rate": 0.0556431,
"interest_base": "calendar_days_365"
},
"iof_amount": 50,
"external_contract_fee_amount": 0,
"external_contract_fees": [],
"contract_fee_amount": 0,
"contract_fees": [],
"number_of_installments": 2,
"disbursed_issue_amount": 997.87,
"final_disbursement_amount": 100,
"issue_amount": 1147.87,
"disbursement_date": "2021-05-31",
"cet": 1.212,
"annual_cet": 32.122
}
],
"disbursement_bank_account": {
"account_digit": "1",
"account_number": "00001",
"ispb": "00000000",
"branch_number": "0001"
}
}

Caso o Parceiro opte por não prosseguir com a Operação de Refinanciamento (Troco), ele deve realizar a seguinte chamada:

ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY/refinancing_credit_operation
MÉTODO
DELETE

Averbação do Refinanciamento (Troco)

Assim que o Parceiro optar por prosseguir com a Operação de Refinanciamento, a rotina para averbação da margem consignável terá início. Assim que a averbação da margem consignável na folha do empregador for concluída o parceiro recebera o seguinte webhook:

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal.collateral
webhook.json
{
"webhook_type": "credit_transfer.proposal.collateral",
"proposal_key": "<PROPOSAL-KEY>",
"event_datetime": "2022-11-24T15:42:12",
"data": {
"credit_operation_type": "refinancing",
"credit_operation_key": "<CREDIT-OPERATION-KEY>",
"collateral_type": "private_payroll",
"collateral_constituted": true
}
}

Desembolso do Refinanciamento (Troco)

Assim que a averbação da margem consignável na folha do empregador for concluída a operação estará pronta para desembolso. No desembolso da Operação de Refinanciamento, a Operação de Portabilidade será quitada e caso exista valor desembolsado remanescente (7.1.1. “disbursement_options.final_disbursement_amount”), este valor será liberado para o cliente (Troco) na conta para desembolso da Operação (“disbursement_bank_account“). A liberação do troco para o cliente pode ser realizada via PIX ou TED, em qualquer horário do dia (obedecendo horário comercial de 7:00 às 17:00 em dias úteis, no caso da TED).

Caso o desembolso do troco para o cliente seja bem sucedido, será enviado um webhook com os dados da comprovação do desembolso:

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal.credit_operation
webhook.json
{
"webhook_type": "credit_transfer.proposal.credit_operation",
"proposal_key": "<PROPOSAL-KEY>",
"event_datetime": "2022-11-24T15:42:12",
"data": {
"credit_operation_status": "disbursed",
"credit_operation_type": "refinancing",
"credit_operation_key": "<CREDIT-OPERATION-KEY>",
"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": "32402502000135",
"bank_code": "329",
"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": "Elaine Isadora da Cruz",
"type": "checking_account",
"bank_code": "033",
"branch": "0001",
"purpose": "Crédito PIX em Conta",
"document_number": "90406718261",
"bank_ispb": "90400888",
"branch_digit": null,
"account_digit": "1",
"account_number": "00001"
},
"end_to_end_id": null,
"transaction_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
"origin_transaction_key": null
}
]
}
}

Caso ocorra falha no desembolso, o parceiro receberá o seguinte webhook:

Falha no desembolso via PIX

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal.credit_operation
webhook.json
{
"webhook_type": "credit_transfer.proposal.credit_operation",
"proposal_key": "60fbbfe2-eb52-4825-9ed5-f169a58b9999",
"event_datetime": "2022-11-24T15:42:12",
"data": {
"credit_operation_status": "canceled",
"credit_operation_type": "refinancing",
"credit_operation_key": "1a1a44df-29b6-431c-89af-53657d906333",
"pix_refusal": {
"reason_enumerator": "invalid_document_number",
"reason": "CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino."
},
"cancel_reason": "pix_refusal"
}
}

Falha no desembolso via TED

Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal.credit_operation
webhook.json
{
"webhook": {
"data": {
"cancel_reason": "Agência ou Conta Destinatária do Crédito Inválida",
"credit_operation_key": "1a1a44df-29b6-431c-89af-53657d906333",
"credit_operation_type": "refinancing",
"credit_operation_status": "canceled",
"cancel_reason_enumerator": "agencia_conta_invalida"
},
"proposal_key": "60fbbfe2-eb52-4825-9ed5-f169a58b9999",
"webhook_type": "credit_transfer.proposal.credit_operation",
"event_datetime": "2023-12-22T10:15:25"
}
}

No caso de falha no desembolso da Operação, o desembolso pode ser retentato alterando-se os dados bancários:

ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY/refinancing_credit_operation
MÉTODO
PATCH
Testar no Playground

Requisição

request.json
{
"disbursement_date": "2022-11-04",
"disbursement_bank_account": {
"account_branch": "1232",
"account_digit": "4",
"account_number": "412412412",
"account_type": "checking_account",
"document_number": "14950479032",
"ispb": "17298092",
"name": "Maria da Silva"
}
}