Solicitar Devolução

Visão Geral

O endpoint PUT /pix/:e2eid/devolucao/:id solicita a devolução de um PIX recebido. Utiliza o End to End ID (e2eid) da transação original e um identificador de devolução gerado pelo cliente.

A devolução pode ser total ou parcial. A soma de todas as devoluções não pode ultrapassar o valor original da transação.

Endpoint

PUT /pix/{e2eid}/devolucao/{id}

Autenticação

string

obrigatório

Token Bearer obtido via /oauth/token.

Parâmetros de URL

string

obrigatório

End to End ID - identificador único da transação PIX original. Contém exatamente 32 caracteres alfanuméricos.Exemplo: E12345678901234567890123456789012

string

obrigatório

Identificação gerada pelo cliente para representar a devolução. Entre 1 e 35 caracteres.Exemplo: D123456789

Request Body

string

obrigatório

Valor solicitado para devolução. String no formato decimal com 2 casas.A soma dos valores de todas as devoluções não pode ultrapassar o valor total do PIX original.Exemplo: "7.89"

string

padrão:"ORIGINAL"

Indica a natureza da devolução solicitada:

ORIGINAL: Devolução de PIX comum ou valor da compra em PIX Troco
RETIRADA: Devolução de PIX Saque ou valor do troco em PIX Troco

string

Texto a ser apresentado ao pagador contendo informações sobre a devolução.Máximo: 140 caracteres.

Request

curl -X PUT https://api.public.firebanking.com.br/pix/E12345678901234567890123456789012/devolucao/D123456789 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": "7.89",
    "natureza": "ORIGINAL",
    "descricao": "Devolução solicitada pelo recebedor"
  }'

const e2eid = 'E12345678901234567890123456789012';
const devolucaoId = 'D123456789';

const response = await fetch(
  `https://api.public.firebanking.com.br/pix/${e2eid}/devolucao/${devolucaoId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      valor: '7.89',
      natureza: 'ORIGINAL',
      descricao: 'Devolução solicitada pelo recebedor',
    }),
  }
);

const devolucao = await response.json();

import requests

e2eid = 'E12345678901234567890123456789012'
devolucao_id = 'D123456789'

response = requests.put(
    f'https://api.public.firebanking.com.br/pix/{e2eid}/devolucao/{devolucao_id}',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json',
    },
    json={
        'valor': '7.89',
        'natureza': 'ORIGINAL',
        'descricao': 'Devolução solicitada pelo recebedor',
    }
)

devolucao = response.json()

Response

201 Created
400 Bad Request
404 Not Found

{
  "id": "D123456789",
  "rtrId": "D12345678901234567890123456789012",
  "valor": "7.89",
  "natureza": "ORIGINAL",
  "descricao": "Devolução solicitada pelo recebedor",
  "horario": {
    "solicitacao": "2024-01-15T10:30:00.000Z"
  },
  "status": "EM_PROCESSAMENTO"
}

{
  "statusCode": 400,
  "message": "Valor deve estar no formato decimal com 2 casas (ex: 7.89)",
  "error": "Bad Request"
}

{
  "statusCode": 404,
  "message": "Transação original não encontrada",
  "error": "Not Found"
}

Campos da Resposta

string

Identificação gerada pelo cliente para representar a devolução (mesmo valor enviado na URL).

string

Identificador único da transação de devolução. Contém 32 caracteres.

string

Valor da devolução no formato string com 2 casas decimais.

string

Natureza da devolução:

ORIGINAL: Devolução comum
RETIRADA: Devolução de saque
MED_OPERACIONAL: Devolução MED por falha operacional
MED_FRAUDE: Devolução MED por suspeita de fraude

string

Mensagem ao pagador relativa à devolução.

object

Mostrar Propriedades

string

Horário no qual a devolução foi solicitada (ISO 8601).

string

Horário no qual a devolução foi liquidada (ISO 8601). Preenchido apenas quando status = DEVOLVIDO.

string

Status da devolução:

EM_PROCESSAMENTO: Devolução em processamento
DEVOLVIDO: Devolução realizada com sucesso
NAO_REALIZADO: Devolução não realizada (falha)

string

Campo opcional com detalhes sobre o motivo do status atual. Preenchido principalmente em caso de falha.

Status da Devolução

Webhook de Devolução

Quando a devolução for processada, você receberá um webhook V2 do tipo REFUND:

{
  "type": "REFUND",
  "data": {
    "id": 123,
    "txId": "original-txid",
    "status": "REFUNDED",
    "payment": {
      "amount": "100.00",
      "currency": "BRL"
    },
    "refunds": [
      {
        "status": "LIQUIDATED",
        "payment": {
          "amount": 7.89,
          "currency": "BRL"
        },
        "endToEndId": "D12345678901234567890123456789012",
        "eventDate": "2024-01-15T10:30:00.000Z",
        "information": "Devolução solicitada pelo recebedor"
      }
    ],
    "endToEndId": "E12345678901234567890123456789012",
    "creditDebitType": "DEBIT"
  }
}

Webhooks REFUND

Veja a documentação completa do webhook REFUND

Natureza da Devolução

Natureza	Descrição
`ORIGINAL`	Devolução de PIX comum
`RETIRADA`	Devolução de PIX Saque ou Troco
`MED_OPERACIONAL`	MED por falha operacional
`MED_FRAUDE`	MED por suspeita de fraude

Os valores MED_OPERACIONAL e MED_FRAUDE são retornados apenas na resposta, não podem ser enviados na requisição. São utilizados em casos específicos de Mecanismo Especial de Devolução (MED).

Prazo para Devolução

Devoluções podem ser solicitadas em até 89 dias após o recebimento do PIX original, conforme regulamentação do Banco Central.

Devoluções Parciais

Você pode solicitar múltiplas devoluções parciais:

// Transação original: R$ 100,00

// Primeira devolução: R$ 30,00
await solicitarDevolucao(e2eid, 'DEV001', '30.00');
// Saldo disponível para devolução: R$ 70,00

// Segunda devolução: R$ 50,00
await solicitarDevolucao(e2eid, 'DEV002', '50.00');
// Saldo disponível para devolução: R$ 20,00

// Terceira devolução: R$ 25,00 - ERRO!
await solicitarDevolucao(e2eid, 'DEV003', '25.00');
// Falha: valor excede saldo disponível (R$ 20,00)

Erros Comuns

Código	Erro	Solução
400	Valor inválido	Use formato “7.89” (string com 2 decimais)
400	Valor excede disponível	Verifique saldo disponível para devolução
404	Transação não encontrada	Verifique o e2eid informado
404	Transação não é do tipo recebimento	Devoluções só para PIX recebidos
422	Prazo expirado	Devoluções só até 89 dias após recebimento

Introdução

Endpoints

Webhooks V2

Visão Geral

Endpoint

Autenticação

Parâmetros de URL

Request Body

Request

Response

Campos da Resposta

Status da Devolução

Webhook de Devolução

Webhooks REFUND

Natureza da Devolução

Prazo para Devolução

Devoluções Parciais

Erros Comuns

Próximos Passos

Transferência PIX

Webhook REFUND

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de URL

​Request Body

​Request

​Response

​Campos da Resposta

​Status da Devolução

​Webhook de Devolução

Webhooks REFUND

​Natureza da Devolução

​Prazo para Devolução

​Devoluções Parciais

​Erros Comuns

​Próximos Passos

Transferência PIX

Webhook REFUND

Visão Geral

Endpoint

Autenticação

Parâmetros de URL

Request Body

Request

Response

Campos da Resposta

Status da Devolução

Webhook de Devolução

Natureza da Devolução

Prazo para Devolução

Devoluções Parciais

Erros Comuns

Próximos Passos