2.4 Claim and Portability

Claiming a PIX key or requiring PIX key portability

ClaimPixKey

Method API = ClaimPixKey

When requesting the registration of a key, it is consulted whether it is already registered in DICT.

• If the Pix key is registered in another institution, but with the same name of the requester, the portability request is recommended.
• If the key is in behalf of another person or company, the claim for ownership can be initiated.

This method performs the request for PIX key claim or portability of any types, however, cannot be used with random keys. This method also applies to situations of claiming keys that are inside FitBank under different ownerships.

Therefore, to claim a PIX key for a FitBank account, you must first attempt to register the key with FitBank using the API method CreatePixKey. If the key in question is a phone or e-mail key, after the creation attempt the API method ConfirmPixKeyHold must be used.
After these steps, the PIX key will change its status to ErrorOwnership. This can be consulted via webhooks and the API method GetPixKeyStatus.

The next step is to use the method ClaimPixKey to request the key claim. Inside FitBank, the key will go through the Claiming status and if the key owner in the external institution confirms the key donation, the claim is successfully completed and the key will have the status Registered in the account that claimed it.

For the Portability flow, the path is the same, the difference is that the key will change its status to ErrorPortability when an attempt is made to create it in FitBank.

{
     "Method": "ClaimPixKey",
     "PartnerId": 30519,
     "BusinessUnitId": 51138,
     "PixKey": "17699384008",
     "TaxNumber": "84928589076",
     "PixKeyType": 0,
     "Bank": "450",
     "BankBranch": "0001",
     "BankAccount": "440246",
     "BankAccountDigit": "3"
}

Description:

Claiming and Portability Status:

• Claiming: The key is in portability and claiming process (within 7 days valid)
• ErrorOwnership: After attempting to create, it was validated that the key is registered with a different owner
• ErrorPortability: It was validated that the key is registered with another institution

Cancel PIX Key Claim

API Method = CancelPixKeyClaim

This method can be used to cancel a Claim request or a Portability request.

{
  "Method": "CancelPixKeyClaim",
  "PartnerId": 152,
  "BusinessUnitId": 136,
  "PixKey": "12345678912",
  "TaxNumber": "12345678912",
  "PixKeyType": 0,
  "Bank": 450,
  "BankBranch": "0001",
  "BankAccount": 499343,
  "BankAccountDigit": 5
}

Description:

Reply External PIX Key Claim

API Method = ReplyExternalPixKeyClaim

This method can be used to respond to a external PIX key claim or PIX key portability. It applies to both key claim flows: when a FitBank account claims a PIX key from another FitBank account, or when an external instituition's account claims or requires portability for a key registered in FitBank.

This operation does not apply to random keys.

The request below occurs when the CPF (Social Security) of the accounts is the same.

The request below occurs when the CPFs (Social Security) of the accounts are different.

{
  "Method": "ReplyExternalPixKeyClaim",
  "PartnerId": 185,
  "BusinessUnitId": 112,
  "PixKey": "[email protected]",
  "PixKeyType": 2,
  "TaxNumber": "36919013000106",
  "Confirmation": 0
}

Description:

FitBank's internal PIX key portability

Change PIX Key

API Method = ChangePixKey

FitBank's API method to perform an internal key portability. Through this method, the user can change the account linked to a PIX key. It applies to FitBank's internal accounts only, and if the source and destination account is from the same owner. This method does not perform this operation with Random Key.

In this case, as in the creation of PIX keys, it is necessary to validate the possession of the PIX key email or phone that the user wants to change the bank details. This validation is done by a numeric token sent to the user via e-mail or SMS, depending on the type of PIX key.

This confirmation can be done by using the API method ConfirmPixKeyHold, and if the token has not been received or expired, use the ResendPixKeyToken method to resend the token and then use ConfirmPixKeyHold method again.

This is necessary to ensure that the person requesting the change of bank details is indeed the owner of the PIX key.

{
     "Method": "ChangePixKey",
     "PartnerId": 30519,
     "BusinessUnitId": 51138,
     "TaxNumber": "84928589076",
     "FromBank": "450",
     "FromBankBranch": "1234",
     "FromBankAccount": "12345",
     "FromBankAccountDigit": "1",
     "PixKey": "17699384008",
     "ToBusinessUnitId": 51062,
     "ToBank": "450",
     "ToBankBranch": "12345",
     "ToBankAccount": "12345677",
     "ToBankAccountDigit": "32641"
}

Description: