Criar contestação - Autoatendimento MED

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.	`^([0-9]{11}\|[A-Z0-9]{12}[0-9]{2})$`

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.

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

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.