Solicitar Devolução

Visão Geral

O endpoint PUT /api/pix/:e2eid/devolucao/:id solicita a devolução de um PIX recebido. Você informa o End to End ID (e2eid) do PIX original e um identificador de devolução gerado pelo seu sistema.

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

Endpoint

PUT https://api.fypay.me/api/pix/{e2eid}/devolucao/{id}

Autenticação

stringobrigatorio

Token Bearer obtido em POST https://api.fypay.me/api/auth/token. Esta rota não usa certificado de cliente.

Identificador do PIX recebido que será devolvido. Aceita o End to End ID (data.endToEndId do webhook RECEIVE) ou o ID numérico da transação na FyPay (loc.id da cobrança ou data.id do webhook).

Exemplo: E12345678202401151030abcdefghijk

idstringobrigatorio

Identificação gerada pelo seu sistema para representar a devolução. Até 100 caracteres e única por conta: repetir um id já usado retorna 400 com o código PIX_DUPLICATE_EXTERNAL_ID.

Exemplo: D123456789

Request Body

stringobrigatorio

Valor solicitado para devolução. String no formato decimal com exatamente 2 casas (^\d{1,10}\.\d{2}$).

A soma dos valores de todas as devoluções não pode ultrapassar o valor do PIX original.

Exemplo: "7.89"

string

Natureza da devolução: ORIGINAL ou RETIRADA. Aceito por compatibilidade com o padrão do Banco Central e devolvido na resposta. Hoje toda devolução é processada como devolução comum, independentemente deste campo.

string

Texto a ser apresentado ao pagador com informações sobre a devolução.

Máximo: 140 caracteres.

Request

curl -X PUT https://api.fypay.me/api/pix/E12345678202401151030abcdefghijk/devolucao/D123456789 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": "7.89",
    "descricao": "Devolução solicitada pelo recebedor"
  }'

const e2eid = 'E12345678202401151030abcdefghijk';
const devolucaoId = 'D123456789';

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

const devolucao = await response.json();

import requests

e2eid = 'E12345678202401151030abcdefghijk'
devolucao_id = 'D123456789'

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

devolucao = response.json()

Response

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

{
  "statusCode": 400,
  "code": "PIX_REFUND_EXCEEDS_AVAILABLE",
  "message": "Refund value (R$ 25.00) exceeds available amount to refund (R$ 20.00)",
  "userMessage": "Valor do reembolso excede o valor disponível.",
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}

{
  "statusCode": 404,
  "code": "PIX_TRANSACTION_NOT_FOUND",
  "message": "Transaction with e2eId E12345678202401151030abcdefghijk not found",
  "userMessage": "Transação não encontrada.",
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}

Campos da Resposta

idstring

Identificação da devolução (o mesmo valor enviado na URL).

rtrIdstring

Identificador da devolução na FyPay: o ID interno da transação de devolução, completado com zeros à esquerda até 32 caracteres. Não é o End to End ID da devolução; esse chega em data.refunds[0].endToEndId no webhook REFUND.

valorstring

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

naturezastring

O valor de natureza enviado (ORIGINAL ou RETIRADA), ou ORIGINAL se omitido.

descricaostring

O texto de descricao enviado, quando houver.

horarioobject

statusstring

Status da devolução no momento da resposta:

EM_PROCESSAMENTO: devolução em processamento (caso normal)
DEVOLVIDO: devolução já liquidada
NAO_REALIZADO: devolução falhou

motivostring

Presente apenas quando status = NAO_REALIZADO, com o texto Erro ao processar devolução.

O resultado final da devolução chega pelo webhook REFUND, nas URLs cadastradas para o evento refund_in com o formato PIX BACEN.

Webhook de Devolução

Quando a devolução for processada, você recebe um webhook do tipo REFUND (trecho):

{
  "data": {
    "id": 12345,
    "txId": "7978c0c97ea847e78e8849634473c1f1",
    "status": "REFUNDED",
    "payment": {
      "amount": "100",
      "currency": "BRL"
    },
    "refunds": [
      {
        "status": "LIQUIDATED",
        "payment": {
          "amount": 7.89,
          "currency": "BRL"
        },
        "errorCode": null,
        "eventDate": "2024-01-15T10:30:00.000Z",
        "endToEndId": "D12345678202401151030abcdefghijk",
        "information": "Devolução solicitada pelo recebedor"
      }
    ],
    "endToEndId": "E12345678202401151030abcdefghijk",
    "creditDebitType": "DEBIT"
  },
  "type": "REFUND"
}

await solicitarDevolucao(e2eid, 'DEV001', '30.00');

await solicitarDevolucao(e2eid, 'DEV002', '50.00');

await solicitarDevolucao(e2eid, 'DEV003', '25.00');

Se o PIX original foi de R$ 100,00, as duas primeiras somam R$ 80,00 e a terceira falha com 400 PIX_REFUND_EXCEEDS_AVAILABLE, porque restam apenas R$ 20,00 para devolver.

Erros Comuns

Código HTTP	`code`	Causa
400	`PUB_REQUEST_BODY_INVALID`	`valor` fora do formato, `natureza` inválida ou `descricao` acima de 140 caracteres
400	`PIX_DUPLICATE_EXTERNAL_ID`	`id` de devolução já usado nesta conta
400	`PIX_REFUND_EXCEEDS_AVAILABLE`	Valor acima do saldo ainda disponível para devolução
400	`PIX_REFUND_DEADLINE_EXCEEDED`	Mais de 89 dias desde o PIX original
400	`PIX_INVALID_TRANSACTION_TYPE_FOR_REFUND`	A transação não é um PIX recebido
400	`PIX_INVALID_TRANSACTION_STATE`	A transação original não está em estado que permita devolução
400	`PIX_TRANSACTION_ACCOUNT_MISMATCH`	A transação pertence a outra conta
401		Token ausente, inválido ou expirado
404	`PIX_TRANSACTION_NOT_FOUND`	Nenhum PIX encontrado para o `e2eid` informado

Solicitar Devolução

Visão Geral

Endpoint

Autenticação

Parâmetros de URL

Request Body

Request

Response

Campos da Resposta

Webhook de Devolução

Webhook REFUND

Prazo para Devolução

Devoluções Parciais

Erros Comuns

Próximos Passos

Transferência PIX

Webhook REFUND

Nesta página

Solicitar Devolução

Propriedades

Webhook REFUND

Transferência PIX

Webhook REFUND

Nesta página