Criar contestação - Autoatendimento MED

A abertura de uma contestação deve ser feita pelo prestador de serviço de pagamento (PSP) do pagador assim que houver suspeita de fraude ou reclamação do cliente. Esse PSP é chamado de participante recuperador, e a transação que origina o processo é denominada transação raiz, sempre vinculada a um cliente pagador. A instauração do processo deve ocorrer de forma imediata, com o objetivo de agilizar o bloqueio dos recursos. A análise do mérito da solicitação é feita posteriormente, permitindo maior eficiência na contenção dos valores envolvidos.

Este endpoint permite que o usuário pagador possa criar uma contestação (MED).

Requisição (Request)

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/pix/branches/{branch}/accounts/{account}/infractions

curl --request POST \
     --url https://api-mtls.sandbox.bankly.com.br/pix/branches/0001/accounts/12345678/infractions \
     --header 'Authorization: token' \
     --header 'accept: application/json' \
     --header 'api-version: 1' \
     --header 'content-type: application/json' \
     --header 'x-bkly-pix-user-id: 12312312387' \
     --data '
{
  "situation": "Scam",
  "endToEndId": "E5958811120250808184150764PB2233",
  "description": "Descrição detalhada do motivo da contestação",
  "requestDate": "2025-07-12T17:56:50.999Z"
}
'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.

Esta requisição requer o scope descrito a seguir:

Scope	Descrição
`pix.infraction-notifications.write`	Concede acesso para criar uma contestação.

Cabeçalhos (Headers)

Nome	Descrição	Especificação
`api-version`	Obrigatório. Versão da API. Atualmente estamos na versão 1.	—
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.	—
`x-bkly-pix-user-id`	Obrigatório. Número do documento do usuário que está fazendo a requisição.	Informe somente números.

Parâmetros da rota (Path)

Nome	Descrição	Especificação
`branch`	Agência do Pagador	—
`account`	Conta do Pagador	—

Corpo da requisição (Body)

No body, envie o seguinte campo em formato JSON:

Nome	Tipo	Descrição
`endToEndId`	`string`	EndToEndId da transação a ser contestada por possível fraude.
`situation`	`string`	Tipo de situação que deu origem à Recuperação de Valores. Enum: `Scam` – Cliente foi induzido ao erro por um golpista e realizou a transação acreditando ser legítima. `AccountTakeover` – Alguém movimentou recursos da conta sem senha e sem conhecimento do titular. `Coercion` – Cliente foi ameaçado ou coagido para realizar a transação. `FraudulentAccess` – Fraudador obteve a senha do cliente e fez transações sem autorização. `Other` – Caso não se enquadre nas categorias anteriores, mas envolva golpe ou fraude. `Unknown` – Não foi possível identificar a causa ou há falta de informações.
`description`	`string`	Detalhes que possam ajudar o PSP na análise. Obrigatório quando `situation` for `Other`
`requestDate`	`dateTime`	Data e hora da solicitação do cliente pagador.

Resposta (Response)

O status code 201 indicará sucesso na criação da notificação de infração.

Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`protocol`	`objeto`	Objeto do protocolo gerado da solicitação de recuperação de valores.
`protocol.number`	`string`	Protocolo gerado da solicitação de recuperação de valores. Formato: YYYYMMDDhhmmssSSSAAA Exemplo: 20250808175650999455.
`protocol.openDate`	`dateTime`	Data e hora da criação da solicitação de recuperação de valores.

Nome

Tipo

Descrição

protocol

objeto

Objeto do protocolo gerado da solicitação de recuperação de valores.

protocol.number

string

Protocolo gerado da solicitação de recuperação de valores.

Formato: YYYYMMDDhhmmssSSSAAA Exemplo: 20250808175650999455.

protocol.openDate

dateTime

Data e hora da criação da solicitação de recuperação de valores.

{
  "protocol": {
    "number": "20250712175650999455",
    "openDate": "2025-07-12T17:56:50.999Z"
  }
}

👍
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status code	Código	Mensagem	Significado
400	INVALID_PARAMETER	—	Um ou mais campos obrigatórios não foram preenchidos.
401	UNAUTHORIZED	—
403	FORBIDDEN	—
422	INFRACTION_ALREADY_EXISTS	A dispute has already been requested for this transaction.	Já existe uma contestação solicitada para essa transação.
422	TRANSACTION_NOT_FOUND	The reported transaction was not found.	A transação informada não foi encontrada.
422	TRANSACTION_STATUS_INVALID	The reported transaction was not successfully completed.	A transação informada não foi completada com sucesso.
422	TRANSACTION_IS_NOT_ALLOWED	The transaction cannot be disputed.	A transação não pode ser contestada.
422	TRANSACTION_IN_PROCESS	The transaction is still being processed at the BACEN.	A transação ainda está sendo processada no Banco Central.
422	TIME_LIMIT_FOR_CONTESTING_HAS_BEEN_EXCEEDED	The maximum deadline to initiate the recovery of funds has been exceeded.	Prazo limite máximo para criar a recuperação de valores foi excedido.
500	UNEXPECTED_ERROR	An unexpected result occurred during the operation.	Ocorreu um erro inesperado durante o processamento.
500	INTERNAL_ERROR	An unknown error occurs to process transaction.

Eventos

Este endpoint não possui eventos relacionados a ele.