Estorno (Refund)

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)

Campo	Tipo	Obrigatório	Descrição
`chargeId`	string	Sim	ID da cobrança a ser estornada
`reason`	string	Sim	Motivo 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

Campo	Tipo	Descrição
`status`	string	Status do estorno: `refunded`, `pending`, `refused` ou `failed`
`reason`	string \| null	Motivo de recusa ou falha, quando aplicável
`pspRefundRefId`	string \| null	ID de referência do estorno no PSP, quando disponível

Valores de `status`

Valor	Significado
`refunded`	Estorno concluído com sucesso
`pending`	Estorno aceito pelo PSP, aguardando processamento final
`refused`	Estorno recusado pelo PSP
`failed`	Falha no processamento

Efeito no charge

Quando o estorno é processado com sucesso (status: "refunded"):

O charge passa a ter status: "refunded".
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.

Introdução

Autenticação

Homologação

Recursos

Webhooks

Estorno (Refund)

Endpoint

Request

Body (JSON)

Pré-condições

Response

Campos da resposta

Valores de `status`

Efeito no charge

Exemplo cURL

Exemplo JavaScript

Referências

​Endpoint

​Request

​Body (JSON)

​Pré-condições

​Response

​Campos da resposta

​Valores de status

​Efeito no charge

​Exemplo cURL

​Exemplo JavaScript

​Referências

Endpoint

Request

Body (JSON)

Pré-condições

Response

Campos da resposta

Valores de `status`

Efeito no charge

Exemplo cURL

Exemplo JavaScript

Referências