Skip to main content
A FastPay permite solicitar o estorno de cobranças pagas via API. O estorno é suportado para cobranças PIX e cartão de crédito.
A API suporta apenas estorno total. Estornos parciais (de valor menor que o original) não são suportados.

​
Endpoint

POST /v1/refunds
Autenticação via Basic Auth com sua API key. Consulte Autenticação se precisar de ajuda com o header.

​
Request

​
Body (JSON)

CampoTipoObrigatórioDescrição
chargeIdstringSimID da cobrança a ser estornada
reasonstringSimMotivo do estorno (texto livre; registrado para auditoria)
{
  "chargeId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "reason": "Solicitação de cancelamento pelo cliente"
}

​
Pré-condições

Para que o estorno seja aceito:
  • O charge deve estar com status: "paid".
  • Não pode existir outro estorno pending ou refunded para o mesmo charge (cada charge comporta apenas um estorno).
Se alguma das condições não for atendida, a API retorna um erro com a descrição do motivo.

​
Response

HTTP 201 Created 
{
  "status": "refunded",
  "reason": null,
  "pspRefundRefId": "psp_refund_abc123xyz"
}

​
Campos da resposta

CampoTipoDescrição
statusstringStatus do estorno: refunded, pending, refused ou failed
reasonstring | nullMotivo de recusa ou falha, quando aplicável
pspRefundRefIdstring | nullID de referência do estorno no PSP, quando disponível

​
Valores de status

ValorSignificado
refundedEstorno concluído com sucesso
pendingEstorno aceito pelo PSP, aguardando processamento final
refusedEstorno recusado pelo PSP
failedFalha no processamento

​
Efeito no charge

Quando o estorno é processado com sucesso (status: "refunded"):
  1. O charge passa a ter status: "refunded".
  2. O webhook charge.refunded é disparado e entregue a todos os webhook endpoints configurados do merchant, além do postback_url da cobrança (se configurado).
Consulte Webhooks de Cobrança para detalhes do payload do evento charge.refunded.

​
Exemplo cURL

curl -X POST "https://api-global.fastpaybrasil.com/v1/refunds" \
  -H "Authorization: Basic $(echo -n 'sua_api_key:' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "chargeId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "reason": "Solicitação de cancelamento pelo cliente"
  }'
Resposta esperada: 
{
  "status": "refunded",
  "reason": null,
  "pspRefundRefId": "psp_refund_abc123xyz"
}

​
Exemplo JavaScript

const apiKey = process.env.FASTPAY_API_KEY;
const credentials = Buffer.from(`${apiKey}:`).toString('base64');

const response = await fetch('https://api-global.fastpaybrasil.com/v1/refunds', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    chargeId: '2RhQg9M7ZCg3X3nMb9W1kX8Q',
    reason: 'Solicitação de cancelamento pelo cliente',
  }),
});

const refund = await response.json();

if (refund.status === 'refunded') {
  console.log('Estorno concluído:', refund.pspRefundRefId);
} else {
  console.warn('Estorno não finalizado:', refund.status, refund.reason);
}
A API não suporta Idempotency-Key. Para evitar estornos duplicados em caso de timeout, consulte o status do charge (GET /v1/charges/:id) antes de reenviar a requisição. Se já houver um estorno pending ou refunded, não envie uma nova solicitação.

​
Referências