Fluxo de Estorno

Visão Geral da Política de Devolução

Cenários de Estorno

Ciclo de Vida do Status do Estorno

  POST /application/{id}/refund
                │
                ▼
        ┌───────────────┐
        │    PENDING     │◄──────────────────────────┐
        │                │                           │
        │  Estorno       │                  Parceiro reenvia
        │  sendo         │                  dados corrigidos
        │  processado    │                           │
        └──┬─────┬────┬──┘                           │
           │     │    │                              │
           │     │    └──────────────┐               │
           │     │                   │               │
           ▼     ▼                   ▼               │
  ┌──────────┐ ┌──────────┐ ┌───────────────────┐   │
  │COMPLETED │ │  FAILED  │ │ ACTION_REQUIRED   │   │
  │          │ │          │ │                   │   │
  │ Estorno  │ │ Estorno  │ │ Problema          │   │
  │ aplicado │ │ não pôde │ │ detectado.        │   │
  │ ao       │ │ ser      │ │ Parceiro chama    │   │
  │ emprésti-│ │ proces-  │ │ PUT /refund/{id}  ├───┘
  │ mo       │ │ sado     │ │ com nova pix_key  │
  └──────────┘ └──────────┘ │ (veja reason)     │
                            └───────────────────┘

O que acontece quando um estorno é COMPLETED?

O resultado financeiro depende de o cliente já ter pago parcelas:

Nota: O campo pix_key é sempre obrigatório na requisição, mas uma transferência PIX ao cliente só ocorre quando há valor excedente (valor da devolução ultrapassa o saldo restante) ou quando o cliente já realizou pagamentos que precisam ser devolvidos.

Quando o ACTION_REQUIRED acontece?

Quando o estorno requer uma transferência PIX ao cliente, mas a chave PIX fornecida é inválida, o status muda para ACTION_REQUIRED. O parceiro deve coletar uma chave PIX corrigida com o cliente e reenviar.

Possíveis valores de reason:

Solicitar um Estorno

POST /application/{application_id}/refund

{
  "amount": 1000,
  "reason": "Customer returned all products",
  "refund_type": "FULL",
  "reason_code": "PRODUCT_RETURN",
  "pix_key": "111.111.111-11",
  "pix_key_type": "CPF"
}

Resposta:

{
  "refund_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "PROCESSING",
  "refunded_at": "2026-01-21T14:00:00Z"
}

Exemplo de Estorno Parcial

POST /application/{application_id}/refund

{
  "amount": 400,
  "reason": "Customer returned 1 of 3 items",
  "refund_type": "PARTIAL",
  "reason_code": "PRODUCT_RETURN",
  "pix_key": "[email protected]",
  "pix_key_type": "EMAIL"
}

Resposta:

{
  "refund_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "PROCESSING",
  "refunded_at": "2026-01-21T14:00:00Z"
}

Consultar Status do Estorno

GET /application/{application_id}/refund/{refund_id}

Estorno concluído:

{
  "application_id": "7ffd813a-1e88-4a4a-a892-758ca310e607",
  "person_id": "8ffd813a-1e88-4a4a-a892-758ca310e607",
  "refund_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "COMPLETED",
  "reason": null,
  "refund_type": "FULL",
  "offset_amount": 1000.00,
  "refund_amount": 220.00,
  "refunded_at": "2026-01-21T14:00:00Z",
  "completed_at": "2026-01-22T10:00:00Z"
}

Ação necessária (chave PIX inválida):

{
  "application_id": "7ffd813a-1e88-4a4a-a892-758ca310e607",
  "person_id": "8ffd813a-1e88-4a4a-a892-758ca310e607",
  "refund_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "ACTION_REQUIRED",
  "reason": "INVALID_PIX_KEY",
  "refund_type": "FULL",
  "offset_amount": 1000.00,
  "refund_amount": 0,
  "refunded_at": "2026-01-21T14:00:00Z",
  "completed_at": null
}

Atualizar Estorno

Quando um estorno está com status ACTION_REQUIRED, use este endpoint para fornecer dados corrigidos. O estorno será automaticamente movido de volta para PENDING e será reprocessado.

PUT /application/{application_id}/refund/{refund_id}

{
  "pix_key": "222.222.222-22",
  "pix_key_type": "CPF"
}

Resposta:

{
  "application_id": "7ffd813a-1e88-4a4a-a892-758ca310e607",
  "person_id": "8ffd813a-1e88-4a4a-a892-758ca310e607",
  "refund_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "PENDING",
  "reason": null,
  "refund_type": "FULL",
  "offset_amount": 500,
  "refund_amount": 0,
  "refunded_at": "2026-01-22T09:00:00Z",
  "completed_at": null
}

Nota: Este endpoint aceita apenas estornos com status ACTION_REQUIRED. Chamá-lo em um estorno com qualquer outro status retornará um erro 409 Conflict.

Webhook de Status do Estorno

O sistema envia uma notificação via webhook (POST /webhooks/refund-status) sempre que um estorno muda de estado. Isso é especialmente útil quando a solicitação original de estorno expirou ou retornou um erro.

{
  "person_id": "8ffd813a-1e88-4a4a-a892-758ca310e607",
  "webhook_type": "refund.status_change",
  "application_id": "7ffd813a-1e88-4a4a-a892-758ca310e607",
  "refund_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "previous_status": "PENDING",
  "new_status": "ACTION_REQUIRED",
  "event_datetime": "2026-01-22T11:00:00Z",
  "data": {
    "refund_amount": 0,
    "refund_type": "FULL",
    "offset_amount": 1000,
    "reason": "INVALID_PIX_KEY"
  }
}

Ao receber ACTION_REQUIRED, colete uma nova chave PIX com o cliente e atualize o estorno usando PUT /application/{application_id}/refund/{refund_id}.

Lógica de Cálculo do Estorno

Para devoluções parciais, o valor da devolução é aplicado como entrada:

Novo Saldo Devedor = Saldo Atual - Valor da Devolução
Nova Parcela = Novo Saldo Devedor / Parcelas Restantes

Exemplo:

• Empréstimo original: R$1.100 (10 parcelas de R$110)
• Pagamentos realizados: 3 parcelas (R$330)
• Saldo devedor: R$770
• Item devolvido: R$300

Resultado:

• Novo saldo: R$770 - R$300 = R$470
• Parcelas restantes: 7
• Nova parcela: R$470 / 7 = R$67,14

Nota

Para devoluções dentro de 7 dias do recebimento, o IOF também é estornado pela QiTech, resultando em uma reversão completa da transação.