v1

latestOpenAPI 3.0.0Apache 2.02026-07-1751129352.2 KB
Pix

Solicitar devolução.

Endpoint para solicitar uma devolução através de um e2eid do Pix e do ID da devolução. O motivo que será atribuído à PACS.004 será "MD06" ou "SL02" de acordo com a aba RTReason da PACS.004 que consta no Catálogo de Mensagens do Pix a depender da natureza da devolução (Vide a descrição deste campo).

put/pix/{e2eid}/devolucao/{id}

Request body

valorstring required

Valor solicitado para devolução. A soma dos valores de todas as devolucões não podem ultrapassar o valor total do Pix.

natureza'ORIGINAL' | 'RETIRADA'

Indica qual é a natureza da devolução solicitada. Uma solicitação de devolução pelo usuário recebedor pode ser relacionada a um Pix comum (com código: MD06 da pacs.004), ou a um Pix de Saque ou Troco (com códigos possíveis: MD06 e SL02 da pacs.004). Na ausência deste campo a natureza deve ser interpretada como sendo de um Pix comum (ORIGINAL).

As naturezas são assim definidas:

  • ORIGINAL: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix comum ou ao valor da compra em um Pix Troco (MD06);
  • RETIRADA: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix Saque ou ao valor do troco em um Pix Troco (SL02).

Os valores de devoluções são sempre limitados aos valores máximos a seguir:

  • Pix comum: o valor da devolução é limitado ao valor do próprio Pix (a natureza nesse caso deve ser: ORIGINAL);
  • Pix Saque: o valor da devolução é limitado ao valor da retirada (a natureza nesse caso deve ser: RETIRADA); e
  • Pix Troco: o valor da devolução é limitado ao valor relativo à compra ou ao troco:
    • Quando a devolução for referente à compra, o valor limita-se ao valor da compra (a natureza nesse caso deve ser ORIGINAL); e
    • Quando a devolução for referente ao troco, o valor limita-se ao valor do troco (a natureza nesse caso deve ser RETIRADA).
descricaostring

O campo descricao, opcional, determina um texto a ser apresentado ao pagador contendo informações sobre a devolução. Esse texto será preenchido, na pacs.004, pelo PSP do recebedor, no campo RemittanceInformation. O tamanho do campo na pacs.004 está limitado a 140 caracteres.

Response

Dados da devolução.

idstring required

Id gerado pelo cliente para representar unicamente uma devolução.

rtrIdstring required

ReturnIdentification que transita na PACS004.

valorstring required

Valor a devolver.

natureza'ORIGINAL' | 'RETIRADA' | 'MED_OPERACIONAL' | 'MED_FRAUDE' | 'MED_PIX_AUTOMATICO'

Indica qual é a natureza da devolução. Uma devolução pode ser relacionada a um Pix comum (com códigos possíveis: MD06, BE08 e FR01 da pacs.004 e REFU da pacs.008), ou a um Pix de Saque ou Troco (com códigos possíveis: MD06 e SL02 da pacs.004). Na ausência deste campo a natureza deve ser interpretada como sendo de um Pix comum (ORIGINAL).

As naturezas são assim definidas:

  • ORIGINAL: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix comum ou ao valor da compra em um Pix Troco (MD06);
  • RETIRADA: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix Saque ou ao valor do troco em um Pix Troco (SL02);
  • MED_OPERACIONAL: quando a devolução ocorre no âmbito do MED por motivo de falha operacional e se refere a um Pix comum (BE08);
  • MED_FRAUDE: quando a devolução ocorre no âmbito do MED por fundada suspeita de fraude e se refere a um Pix comum (FR01).
  • MED_PIX_AUTOMATICO: reembolso total ou parcial ao participante do usuário pagador no âmbito do MED (Mecanismo Especial de Devolução) para o Pix Automático pela utilização de recursos próprios para ressarcimento do usuário pagador.(REFU);

Os valores de devoluções são sempre limitados aos valores máximos a seguir:

  • Pix comum: o valor da devolução é limitado ao valor do próprio Pix (a natureza nesse caso pode ser: ORIGINAL, MED_OPERACIONAL ou MED_FRAUDE);
  • Pix Saque: o valor da devolução é limitado ao valor da retirada (a natureza nesse caso deve ser: RETIRADA); e
  • Pix Troco: o valor da devolução é limitado ao valor relativo à compra ou ao troco:
    • Quando a devolução for referente à compra, o valor limita-se ao valor da compra (a natureza nesse caso deve ser ORIGINAL); e
    • Quando a devolução for referente ao troco, o valor limita-se ao valor do troco (a natureza nesse caso deve ser RETIRADA).
descricaostring

O campo descricao, opcional, determina um texto a ser apresentado ao pagador contendo informações sobre a devolução. Esse texto será preenchido, na pacs.004, pelo PSP do recebedor, no campo RemittanceInformation. O tamanho do campo na pacs.004 está limitado a 140 caracteres.

status'EM_PROCESSAMENTO' | 'DEVOLVIDO' | 'NAO_REALIZADO' required

Status da devolução.

motivostring

Status da Devolução

Campo opcional que pode ser utilizado pelo PSP recebedor para detalhar os motivos de a devolução ter atingido o status em questão. Pode ser utilizado, por exemplo, para detalhar o motivo de a devolução não ter sido realizada.

Example response

{
  "rtrId": "D12345678202009091000abcde123456"
}