Out Portability

Attention!

QI Tech webhooks should not be mapped restrictively. Additional fields may be included in the webhook payloads returned by our APIs.

Webhook Resend

You can consult and resend webhooks following the detailed instructions in the documentation: Webhook Resend.

1. Out portability receipt notification

As soon as a portability request is received by QI SCD via CTC (Credit Transfer Center), the partner will be notified through the following webhook:

WEBHOOK_TYPE

credit_transfer.received_portability

STATUS

Received

Webhook Body

{
    "webhook_type": "credit_transfer.received_portability",
    "received_portability_status": "received", 
    "key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
    "event_datetime": "2022-07-24T18:29:45",  
    "data": {
        "annual_interest_rate": "20.27",
        "annual_effective_interest_rate": "20.27",
        "number_of_installments": "6",
        "installment_face_value": "201.71",
        "phone_number": "(05)541997558",
        "address": {
            "street": "Rua Longe de Casa",
            "city": "Rio de Janeiro",
            "state": "RJ",
            "number": "112",
            "postal_code": "38300569"
        },
        "due_balance": "1000",
        "due_balance_date": "2022-07-29",
        "issuer_name": "A Random Name",
        "issuer_document_number": "37197645832",
        "reference_date": "2022-08-01",
        "contract_number": "0000049045/UO",
        "origin_credit_operation_key": "7daef1ad-5497-4ec3-92f4-26f8d63bcd80",
        "retention_limit_date": "2022-08-03", 
        "due_balance_limit_date": "2022-08-08", 
        "portability_number": "202207150000001642808",
        "corban_document_number": "08289470514408",
        "source_ispb_number": "0"
    }
}

Check the field descriptions in the table received_portability webhook details

2. Response to portability attack

2.1. Contract retention

Webhook Resend

To retain the client, the partner must upload the retention evidence and attach them to the operation by 6:00 PM on the 4th business day after receiving the attack event (credit_transfer.received_portability).

ENDPOINT

/credit_transfer/received_portability/[received_portability_key]

METHOD

PATCH

Test in Playground

{
  "received_portability_status": "retained",
  "retention_reason": "issuer_retention",
  "document_type": "received_portability_retention_proof",
  "documents": [
    {
      "file_type": "jpeg",
      "document_key": "3d6fbbbf-55e9-4275-8050-b83b33fdefa6",
    }
  ]
}

Attention

COMPRESSED files will NOT be accepted.

Check the request field descriptions in the Table

2.2 Out portability approval

If the client is not retained, the partner must inform about the non-retention by 10:00 AM on the 4th business day after receiving the portability attack notification (credit_transfer.received_portability).

Attention

If the portability request is not responded to within 4 business days, QI Tech will return the operation's outstanding balance to the proposer (portability requester).

ENDPOINT

/credit_transfer/received_portability/[received_portability_key]

METHOD

PATCH

Test in Playground

Request Body
{
	"received_portability_status": "accepted_by_creditor"
}

3. Querying out portability requests

3.1. Portability request query

To check the possible statuses of the

ENDPOINT

/credit_transfer/received_portability/[received_portability_key]

METHOD

GET

Test in Playground

Response Body

{
	"received_portability_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
	"received_portability_status": "accepted",
	"annual_interest_rate": "20.27",
	"annual_effective_interest_rate": "20.27",
	"number_of_installments": "6",
	"installment_face_value": "201.71",
	"phone_number": "(05)541997558",
	"address": {
		"street": "Rua Longe de Casa",
		"city": "Rio de Janeiro",
		"state": "RJ",
		"number": "112",
		"postal_code": "38300569"
	},
	"due_balance": 1000,
	"due_balance_date": "2022-07-29",
	"issuer_name": "A Random Name",
	"issuer_document_number": "37197645832",
	"reference_date": "2022-08-01",
	"contract_number": "0000049045/UO",
	"origin_credit_operation_key": "key",
	"retention_limit_date": "2022-08-03",
	"due_balance_limit_date": "2022-08-08",
	"portability_number": "202207150000001642808",
	"retention_reason": null,
	"canceled_reason": null,
  "corban_document_number": "08289470514408",
  "attached_documents": [
    ],
  "financial_institution_code_number": "001",
  "financial_institution_name": "Banco do Brasil",
  "ispb": "00000000",
  "requester_key": "8511012c-3a3c-4f4d-9f23-dbe437211a8e",
  "requester_name": "Corban LTDA",
  "response_date": null,
  "settlement_date": null,
  "settlement_due_balance": null
}

3.2. List portability request

ENDPOINT

/credit_transfer/received_portability

METHOD

GET

PARAMETERS

settlement_date, max_portability_date, due_balance_limit_date, received_portability_status, portability_number, contract_number, credit_operation_key

Test in Playground

Response Body

{
	"data": [{
		"received_portability_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
		"received_portability_status": "accepted",
		"annual_interest_rate": 1,
		"annual_effective_interest_rate": 1,
		"number_of_installments": 6,
		"installment_face_value": 201.71,
		"phone_number": "(05)541997558",
		"address": {
			"street": "Rua Longe de Casa",
			"city": "Rio de Janeiro",
			"state": "RJ",
			"number": "112",
			"postal_code": "38300569"
		},
		"due_balance": 1000,
		"due_balance_date": "2022-07-29",
		"issuer_name": "A Random Name",
		"issuer_document_number": "37197645832",
		"reference_date": "2022-08-01",
		"contract_number": "0000049045/UO",
		"origin_credit_operation_key": "key",
		"retention_limit_date": "2022-08-03",
		"due_balance_limit_date": "2022-08-08",
		"portability_number": "202207150000001642808",
		"retention_reason": null,
		"canceled_reason": null
	}],
	"pagination": {
		"next_page": null,
		"current_page": 1,
		"total_rows": 0,
		"rows_per_page": 1,
		"total_pages": 0
	}
}

4. Webhooks

Below are the possible webhooks received during the flow, the state machine can be consulted to check possible status changes (the canceled_by_proponent status can be reached from any non-final status)

4.1. Waiting for outstanding balance payment

WEBHOOK_TYPE

credit_transfer.received_portability

STATUS

waiting_settlement

Webhook Body
{
  "webhook_type": "credit_transfer.received_portability",

  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "waiting_settlement",
  "event_datetime": "2022-07-24T18:29:45",
  "data": {
    "settlement_due_balance": 120.00,
    "settlement_date": "2022-08-02"
  }
}

4.2. Proposal canceled by proposer

WEBHOOK_TYPE

credit_transfer.received_portability

STATUS

canceled_by_proponent

Webhook Body
{
  "webhook_type": "credit_transfer.received_portability",
  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "canceled_by_proponent",
  "event_datetime": "2022-07-24T18:29:45",
  "data": {}
}

4.3. Portability settled

WEBHOOK_TYPE

credit_transfer.received_portability

STATUS

settled

Webhook Body
{
  "webhook_type": "credit_transfer.received_portability",
  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "settled",
  "event_datetime": "2022-07-24T18:29:45Z",
  "data": {}
}

4.4. Portability not settled

If the proposer does not make payment of the outstanding balance returned in the out portability response (portability attack), the proposal will be canceled for lack of payment within the deadline.

WEBHOOK_TYPE

credit_transfer.received_portability

STATUS

canceled_by_creditor

Webhook Body
{
  "webhook_type": "credit_transfer.received_portability",
  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "canceled_by_creditor",
  "event_datetime": "2022-07-24T18:29:45",
  "data": {
   "canceled_reason": {
    "enumerator": "not_paid",
    "description": "Decurso de prazo por STR não paga dentro do prazo"
   }
  }
}

5. Sandbox validation mocks

Sandbox Environment

Use these endpoints to simulate the out portability flow in sandbox without relying on real CTC/STR events.

Important Notice!

Do not use real personal data (CPF, CNPJ, etc.) in sandbox environments.

5.1. Simulate received portability

Calling this endpoint will trigger the credit_transfer.received_portability webhook (described in section 1) with data computed from the provided credit operation.

ENDPOINT

/mock/credit_transfer/received_portability

METHOD

POST

Attributes

credit_operation_keystring (UUID)requiredKey of the credit operation to port.reference_datestringrequiredReference date for the portability (format YYYY-MM-DD).ispb_numberstringrequiredISPB number of the origin institution (max 8 chars).origin_contract_typestringoptionalType of the origin contract. Allowed values: payroll, public_agency. Default: payroll.proposal_typestringoptionalProposal type. Allowed values: inss. Default: inss.

Request Body
{
  "credit_operation_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reference_date": "2026-04-13",
  "ispb_number": "00000000",
  "origin_contract_type": "payroll",
  "proposal_type": "inss"
}

Response — 202 Accepted
{}

5.2. Simulate STR settlement

After approving the portability (section 2.2) and receiving the waiting_settlement webhook (section 4.1), use this endpoint to simulate the settlement or payment rejection via STR. The corresponding webhook (settled or canceled_by_creditor) will be triggered according to the chosen event_type.

ENDPOINT

/mock/credit_transfer/str

METHOD

POST

Attributes

proposal_keystring (UUID)requiredKey of the proposal (returned in the waiting_settlement webhook).event_typestringrequiredEvent type. Allowed values: settlement, payment_rejected.source_branchstringoptionalSource branch code. Default: "0001".target_branchstringoptionalTarget branch code. Default: "0001".provider_ispbstringoptionalProvider ISPB number. Default: "99999999".

Request Body (settlement)
{
  "proposal_key": "9ff557c3-b640-4862-b2c1-ef6f7d9a6a61",
  "event_type": "settlement",
  "source_branch": "0001",
  "target_branch": "0001",
  "provider_ispb": "99999999"
}

Response — 202 Accepted
{}

Annexes

received_portability webhook details

Field	Description
key	Attack key (received_portability_key)
webhook_type	Event type
received_portability_status	Attack status
event_datetime	Event date
annual_interest_rate	Rate informed in the attack
annual_effective_interest_rate	CET informed in the attack
number_of_installments	Number of installments informed in the attack
installment_face_value	Installment amount informed in the attack
phone_number	Phone number informed in the attack
address	Address informed in the attack
due_balance	Outstanding balance informed in the attack
due_balance_date	Outstanding balance reference date informed in the attack
issuer_name	Borrower name informed in the attack
issuer_document_number	Borrower document number informed in the attack
reference_date	informed in the attack
contract_number	Contract number informed in the attack
origin_credit_operation_key	Credit operation key (DEBT_KEY/CREDIT_OPERATION_KEY)
retention_limit_date	Retention deadline
due_balance_limit_date	Outstanding balance information deadline
portability_number	Portability number (NU)
corban_document_number	informed in the attack
source_ispb_number	informed in the attack

authorization_term object details

Field	Requirement	Description
received_portability_status	Required	Balance release or not
retention_reason	Required in case of retention	Retention reason, check possible enumerators in the Retention reason table
document_type	Required in case of retention	Necessarily "received_portability_retention_proof"
documents	Required in case of retention	Retention evidence
file_type	Required in case of retention	Document type, check possible enumerators in the Document type table
document_key	Required in case of retention	Document key returned after upload

Retention reason

Enumerator	Description
issuer_retention	Client Retention
portability_not_requested	Client did not request portability

Document type

enumerator
pdf
jpeg
jpg
png
mp3
wav

Attack status

Enumerator	Description
received	Received
waiting_validation	Waiting for Retention Proof Document validation
canceled_by_proponent	Canceled by Proposer
canceled_by_creditor	Canceled by Original Creditor
retained	Retained
waiting_settlement	Portability approved awaiting settlement
settled	Settled

1. Out portability receipt notification​

2. Response to portability attack​

2.1. Contract retention​

2.2 Out portability approval​

3. Querying out portability requests​

3.1. Portability request query​

3.2. List portability request​

4. Webhooks​

4.1. Waiting for outstanding balance payment​

4.2. Proposal canceled by proposer​

4.3. Portability settled​

4.4. Portability not settled​

5. Sandbox validation mocks​

5.1. Simulate received portability​

Attributes​

5.2. Simulate STR settlement​

Attributes​

Annexes​

received_portability webhook details​

authorization_term object details​

Retention reason​

Document type​

Attack status​

Attack state machine​

1. Out portability receipt notification

2. Response to portability attack

2.1. Contract retention

2.2 Out portability approval

3. Querying out portability requests

3.1. Portability request query

3.2. List portability request

4. Webhooks

4.1. Waiting for outstanding balance payment

4.2. Proposal canceled by proposer

4.3. Portability settled

4.4. Portability not settled

5. Sandbox validation mocks

5.1. Simulate received portability

Attributes

5.2. Simulate STR settlement

Attributes

Annexes

received_portability webhook details

authorization_term object details

Retention reason

Document type

Attack status

Attack state machine