Reivindicação de chave (posse e portabilidade)

O endpoint de reivindicação de chaves Pix possibilita solicitar a portabilidade ou a posse de uma chave Pix, de acordo com a necessidade de seu cliente.

Criação de pedido de reivindicação

Endpoint

Para utilizar o endpoint de criação de um pedido de reivindicação de chaves, preencha obrigatoriamente os campos descritos a seguir.

Header

x-bkly-pix-user-id: número do documento do cliente que está fazendo a requisição. Insira apenas números, sem formatação.

Body

type: tipo de pedido, que pode ser "PORTABILITY", para portabilidade, e "OWNERSHIP", para posse;
addressingKey: objeto que contém os dados da chave Pix:
- type: tipo de chave de endereçamento (CPF, CNPJ, EVP, e-mail ou telefone);
- value: valor da chave.
claimer: objeto que contém os dados da conta do reivindicador:
- branch: número da agência bancária;
- number: número da conta.
bank: objeto que contém os dados do banco do reivindicador:
- name: nome da instituição de pagamento;
- ispb: no caso, o valor a ser preenchido é “13140088”.

curl --location --request POST 'https://api-mtls.sandbox.bankly.com.br/pix/claims' \ 
--header 'api-version: 1' \ 
--header 'x-bkly-pix-user-id: {{document_number}}' \ 
--header 'Content-Type: application/json' \ 
--header 'Accept: application/json' \ 
--header 'Authorization: Bearer {{access_token}}' \ 
--data-raw '{ 
  "type": "PORTABILITY", 
  "addressingKey": { 
    "type": "CPF", 
    "value": "{{document_number}}" 
  }, 
  "claimer": { 
    "branch": "0001", 
    "number": "123456", 
    "bank": { 
      "name": "Acesso Soluções de Pagamento S.A", 
      "ispb": "13140088" 
    } 
  } 
}'

curl --location --request POST 'https://api-mtls.sandbox.bankly.com.br/pix/claims' \ 
--header 'api-version: 1' \ 
--header 'x-bkly-pix-user-id: {{document_number}}' \ 
--header 'Content-Type: application/json' \ 
--header 'Accept: application/json' \ 
--header 'Authorization: Bearer {{access_token}}' \ 
--data-raw '{ 
  "type": "OWNERSHIP", 
  "addressingKey": { 
    "type": "PHONE", 
    "value": "{{phone_number}}" 
  }, 
  "claimer": { 
    "branch": "0001", 
    "number": "123456", 
    "bank": { 
      "name": "Acesso Soluções de Pagamento S.A", 
      "ispb": "13140088" 
    } 
  } 
}'

Retorno

O sucesso na requisição retornará o status code 201.

Dentre as informações retornadas, destacamos os campos:

claimId: identificação única de pedido de portabilidade ou posse. Esse valor deverá ser utilizado todas as vezes que você realizar uma operação referente a essa reivindicação, como consulta, cancelamento etc.;
resolutionLimitDate: data limite para o doador de portabilidade realizar ações, como concluir ou cancelar o pedido de reivindicação. Formato: aaaa-mm-ddTHH:mm:ss.sssZ;
conclusionLimitDate: data limite para o doador de posse e o reivindicador (tanto de posse como de portabilidade) confirmarem ou cancelarem o pedido. Formato: aaaa-mm-ddTHH:mm:ss.sssZ.

🚧
Importante
No caso de reivindicação de portabilidade, se a instituição doadora não responder o pedido em sete dias (cujo limite é indicado no campo resolutionLimitDate), ele é automaticamente cancelado e a chave permanece na mesma conta onde está cadastrada.
Já no fluxo de reivindicação de posse, se não houver uma resposta dentro de 14 dias (cujo limite é indicado no campo conclusionLimitDate), a chave passará para quem a reivindicou.

{ 
    "claimId": "string", 
    "type": "PORTABILITY", 
    "addressingKey": { 
        "type": "CPF", 
        "value": "12345678900" 
    }, 
    "claimer": { 
        "branch": "0001", 
        "number": "240559", 
        "bank": { 
            "name": "Acesso Soluções de Pagamento S.A", 
            "ispb": "13140088" 
        } 
    }, 
    "status": "OPEN", 
    "createdAt": "2022-06-21T15:05:42.4626073Z", 
    "resolutionLimitDate": "2022-06-28T15:05:42.4626073Z", 
    "conclusionLimitDate": "2022-07-05T15:05:42.4626073Z" 
}

{ 
    "claimId": "string", 
    "type": "ONERSHIP", 
    "addressingKey": { 
        "type": "PHONE", 
        "value": "+55912345678" 
    }, 
    "claimer": { 
        "branch": "0001", 
        "number": "123456", 
        "bank": { 
            "name": "Acesso Soluções de Pagamento S.A", 
            "ispb": "13140088" 
        } 
    }, 
    "status": "OPEN", 
    "createdAt": "2022-06-21T12:50:13.2630147Z", 
    "resolutionLimitDate": "2022-06-28T12:50:13.2630147Z", 
    "conclusionLimitDate": "2022-07-05T12:50:13.2630147Z" 
}

Erros

Status code	Código	Descrição
422	CANNOT_REGISTER_CLAIM_TO_EVP_TYPE	Não é possível reivindicar a portabilidade e a posse de uma chave do tipo EVP.
422	CANNOT_REGISTER_OWNERSHIP_CLAIM_TO_CPF_TYPE	Não é possível reivindicar a posse de uma chave do tipo CPF.
422	CANNOT_REGISTER_OWNERSHIP_CLAIM_TO_CNPJ_TYPE	Não é possível reivindicar a posse de uma chave do tipo CNPJ.
422	CLAIM_CAN_ONLY_BE_REGISTERED_BY_CLAIMER_ACCOUNT_HOLDER	A reivindicação de portabilidade e de posse somente pode ser feita pelo titular da conta.
422	INVALID_CLAIM_TYPE_USED_ON_REQUEST	O tipo de reivindicação informado é incorreto. Esse erro pode ocorrer quando a pessoa que reivindica a posse já é proprietária da chave (o correto seria solicitar a portabilidade). Ou então, quando a pessoa reivindica a portabilidade de uma chave que está em posse de outra pessoa (o correto seria solicitar a posse).
422	CLAIM_RESULTING_ENTRY_ALREADY_EXISTS	O vínculo com a chave reivindicada já existe.
422	CLAIM_ALREADY_EXISTS_FOR_ENTRY	A reivindicação já existe para essa chave de endereçamento.

Criação de pedido de reivindicação

Endpoint

Retorno

🚧Importante

Erros

🚧
Importante