Creating a Portability Request

Attention

Two-factor authentication is required if the type of key for which portability is being requested is a phone number or email. The token will be sent to the requested number or email. If two-factor authentication is required, the "claim_request_status" will be "pending_claimer_validation". Instructions for sending the token are in the section 2.5.3.5.2 Two-Factor Authentication

Attention!!

The creation of the portability request must be done using one of the mock Pix keys provided for the sandbox environment. Mock Pix Keys

Request

ENDPOINT

/baas/pix/key_claim_request

METHOD

POST

Request Body

{
  "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
  "pix_key": "12345678000190",
  "pix_key_type": "cnpj"
}

Body Params

Field	Type	Description	Characters
account_key	string	Identification key of the QI account.	36
pix_key	enum	Key for which portability is being requested.	-
pix_key_type	enum	Type of pix key for portability.	Enumerators

Enumerators pix_key_type

Enumerator	Translation
random_key	aleatória
email	e-mail
phone_number	número de telefone
cpf	cpf
cnpj	cnpj

Types of Pix Key

The “pix_key” can be a CPF, CNPJ, Email, Mobile Number, or a Random Key (UUID), following these formats: CPF: Integer number with 11 digits. CNPJ: Integer number with 14 digits. Email: Text containing at least one “@”. Mobile Number: Text containing the following values: “+55” + “Cell Phone Area Code“ + “Cell Phone Number with a minimum of 8 and a maximum of 9 digits”. Example: “+5511987654321“. Random Key: UUID.

Response

STATUS

200

Response Body

{
  "max_conclusion_date": "2023-05-26T12:13:25",
  "claim_request_status": "pending",
  "claimant": {
    "document_number": "12345678000190",
    "claimant_key": "6aaadfbc-76ba-45d2-bb21-138bcb2baa62",
    "account_opened_at": "2023-01-17T12:28:37",
    "account_branch": "0001",
    "account_type": "escrow",
    "account_number": "7336349",
    "person_type": "legal",
    "account_digit": "0"
  },
  "max_resolution_date": "2023-05-19T12:13:25",
  "claimant_bank_name": "QI SCD S.A.",
  "pix_key": {
    "pix_key_type": "cnpj",
    "pix_key_status": "pending_confirmation",
    "created_at": "2023-05-12T12:13:24",
    "updated_at": "2023-05-12T12:13:24",
    "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
    "pix_key": "12345678000190"
  },
  "donator_ispb": null,
  "external_key": null,
  "claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
  "claim_request_type": "portability",
  "client_role": "claimant",
  "confirmation_reason": null,
  "requester_key": "e151044c-44d0-48b3-9df1-0b9475077fe5",
  "claimant_bank_code": "329",
  "cancelled_by": null,
  "request_failure_reason": null,
  "donator": null,
  "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j"
}

STATUS

4XX

Response Body: Error

{
  "title": "titulo",
  "description": "description in English",
  "translation": "description in Portuguese",
  "code": "codigo",
  "extra_fields": {}
}

HTTP Code	QI Code code	Title title	Description (eng) Description	Description (ptbr) translation
400	PIX000022	Pix key already registered	Pix key already registered for the account.	Chave pix já cadastrada para a conta.
400	PIX000014	Maximum Number of Pix Keys in Use	Maximum number of pix keys for account {account_key} has reached	A conta {account_key} já tem o número máximo de chaves pix.
400	PIX000003	Account is not Opened	Account {account_key} is not opened	Conta {account_key} não está aberta
400	PIX000053	Invalid Portability Request	Portability within same Financial Institution should follow key alteration flow instead	Não é possível realizar portabilidade dentro da própria instituição financeira. Proceder com o fluxo de alteração
403	PIX000054	Invalid Permission	Person 5dbd5598-6b42-4d80-8e5e-1c616cf8b9ab does not have administration roles for account 169010e3-6c1e-4521-9253-11cbbf36c59j.	Pessoa 5dbd5598-6b42-4d80-8e5e-1c616cf8b9ab não tem credencial de administrador para a conta 169010e3-6c1e-4521-9253-11cbbf36c59j.
404	PIX000017	Pix Key is Unregistered	Pix key 12345678000190 is not currently used.	A chave pix 12345678000190 não está sendo utilizada.
422	PIX000077	Error when querying pix key	Error when querying pix key 12345678000190	Erro ao consultar chave pix 12345678000190
400	PIX000028	Key Type not allowed for portability or claim	Only cpf, cnpj, email and phone_number key_types can be portabilized or claim. Received key_type: random_key	Somente os key_types cpf, cnpj, email e phone_number podem ser portabilizados ou reivindicados. key_type recebido: random_key
400	PIX000061	Invalid Document	Invalid document sent 12345678000190.	Documento enviado é inválido 12345678000190.
404	PIX000026	Account not found	Account not found for account_key: 6aaadfbc-76ba-45d2-bb21-138bcb2baa62	Conta não encontrada para account_key: 6aaadfbc-76ba-45d2-bb21-138bcb2baa62
404	PIX000027	Person not found	Person not found for person_key: {person_key}	Pessoa não encontrada para person_key: {person_key}
422	PIX000069	Pix Key inquiry timeout	Pix key inquiry timeout. Please try again.	Consulta de chave pix excedeu o tempo limite. Por favor tente novamente.
400	PIX000072	Pix Key Claim Non Finished	Pix key 12345678000190, already has a claim request non finished.	Chave pix 12345678000190, já possui um pedido de portabilidade não finalizado.