Copy page

Plataforma

Reembolsos

A API de Reembolsos permite que comerciantes devolvam fundos ao pagador após uma solicitação de pagamento atingir um estado reembolsável. Reembolsos estão no escopo da organização ou conta que possui o ponto de venda da solicitação de pagamento.

Visão geral

Quando você cria um reembolso, a Fluxis:

1. Valida que suas credenciais de API podem acessar o POS da solicitação de pagamento
2. Verifica se a solicitação está em um status elegível
3. Cria um registro de reembolso em status processing
4. Envia um webhook refund (se configurado) com o status inicial

Status elegíveis da solicitação de pagamento

Reembolsos só podem ser criados quando a solicitação de pagamento está em um destes status:

Status	Uso típico
completed	Pagamento integral recebido; reembolsar o valor pago
overpaid	Pagador enviou mais que o solicitado
underpaid	Pagador enviou menos que o solicitado
confirmed	Transação contábil criada após o pagamento

Solicitações em pending, created, processing, expired ou failed não são elegíveis.

Autenticação

Todos os endpoints de reembolso exigem ambos os cabeçalhos:

• Authorization: Bearer <access_token>
• x-fluxis-api-key: <your_api_key>

Consulte Autenticação e configuração para troca de token.

Criar um reembolso

Code
POST /v1/refunds/payment-request/{paymentRequestID}

Corpo da requisição

Campo	Obrigatório	Descrição
refund_to_address	Sim	Endereço blockchain que receberá o reembolso
amount	Não	String decimal. Se omitido, usa o valor registrado da solicitação de pagamento
reason	Não	Motivo em texto livre para auditoria

Exemplo

Code
curl -X POST "https://api.fluxis.us/v1/refunds/payment-request/aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "refund_to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "50.00",
    "reason": "Customer overpaid"
  }'

Resposta (200)

Code
{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "refund_to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "50.00",
    "status": "processing"
  }
}

Obter detalhes do reembolso

Code
GET /v1/refunds/{refundID}

Retorna metadados completos do reembolso, incluindo rede, ativo, hash da transação de pagamento original e refund_transaction_hash após a conclusão do processamento on-chain.

Campo	Descrição
status	processing, completed ou failed
payment_transaction_hash	Hash do pagamento recebido original
refund_transaction_hash	Hash do reembolso de saída (presente após execução on-chain)
unique_asset_id	Identificador do ativo (ex.: Polygon USDC)
network	Rede blockchain do reembolso

Você só pode recuperar reembolsos criados pela mesma entidade autenticada (organização ou conta).

Status de reembolso

Status	Significado
processing	Registro de reembolso criado; transferência on-chain pendente
completed	Transação de reembolso confirmada on-chain
failed	Reembolso não pôde ser concluído

Hoje, reembolsos recém-criados permanecem em processing até que a execução on-chain seja implementada.

Webhooks

Registre um webhook com event_type: "refund" em nível de conta. Na criação, a Fluxis envia:

Code
{
  "data": {
    "notification_type": "refund_status_update",
    "refund_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "payment_request_id": "aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf",
    "status": "processing",
    "amount": "50.00"
  }
}

Verifique cada entrega usando Verificação de assinatura de webhook. Consulte Eventos de webhook para o catálogo completo de eventos.

Erros comuns

HTTP	Causa
400	ID de solicitação inválido, valor ou status de solicitação inelegível
403	Credenciais de API sem permissão para o POS da solicitação de pagamento
404	Reembolso não encontrado (apenas GET)

Documentação relacionada

• Solicitações de pagamento — ciclo de vida e estados extremos
• Eventos de webhook — payload do evento refund
• Transações — registros contábeis após confirmação de pagamento