Reembolsos

Quando o comprador pede o dinheiro de volta pelo formulário da Ephra, nasce uma solicitação de reembolso — e ela espera a sua decisão. Este domínio tem 7 operações: a fila, as duas decisões, a exportação, o quiz de retenção e as contestações de cartão.

Se a decisão já foi tomada fora da Ephra e você só quer devolver o dinheiro, o caminho é outro: POST /v1/transactions/{transactionId}/refund, em Vendas.

1. Leia a fila

curl -s "https://api.ephra.io/v1/refund-requests?page=1&pageSize=5&status=pending" \
  -H "Authorization: Bearer $TOKEN"

Fila vazia é uma resposta bem-sucedida com data vazio:

{
  "success": true,
  "data": [],
  "pagination": { "page": 1, "pageSize": 5, "total": 0, "totalPages": 0 }
}

Sem o filtro, você vê o histórico inteiro:

{
  "success": true,
  "data": [
    {
      "id": 13,
      "transactionId": "cmtxyt3710000eag1smxe72ee",
      "status": "approved",
      "reason": "Comprador desistiu dentro do prazo de garantia de 7 dias.",
      "reasonType": "manual",
      "requestedBy": "gateway:webhook",
      "rejectionReason": null,
      "approvalReason": null,
      "reviewedAt": "2026-09-12T05:50:11.786Z",
      "autoApproveAt": null,
      "amount": 49900,
      "paymentMethod": "pix",
      "refundChannel": null,
      "customer": {
        "name": "Mariana Ribeiro Alves",
        "email": "mariana.alves@empresadela.com.br",
        "document": "39053344705",
        "phone": "+5521997766554"
      },
      "items": [
        { "id": 32, "name": "Curso de Tráfego Pago", "quantity": 1, "unitPrice": 49900 }
      ],
      "createdAt": "2026-09-12T05:50:09.016Z",
      "updatedAt": "2026-09-12T05:50:11.788Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 5, "total": 1, "totalPages": 1 }
}

Os campos que decidem o seu fluxo:

Campo	Para quê
`status`	`pending` espera decisão; `approved` e `rejected` já foram resolvidos
`autoApproveAt`	Quando a Ephra aprova sozinha se você não responder. `null` significa sem prazo
`requestedBy`	Quem abriu: o comprador, o painel, ou um webhook do adquirente
`reasonType`	Se o motivo veio de um formulário livre (`manual`) ou de uma opção do quiz
`amount`	Valor em centavos que volta ao comprador

autoApproveAt é o relógio correndo contra você. Se a sua integração só varre a fila uma vez por dia, pedidos com prazo curto serão aprovados automaticamente antes de você olhar. Ordene por autoApproveAt e trate os mais próximos primeiro.

Filtros disponíveis: status, refundChannel, startDate, endDate e search (nome, e-mail ou documento do comprador).

2. Aprove

curl -s -X POST https://api.ephra.io/v1/refund-requests/48127/approve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Comprador relatou falha de acesso à área de membros."}'

{
  "success": true,
  "data": {
    "id": 48127,
    "status": "approved",
    "refundChannel": "api",
    "message": "Reembolso aprovado e processado no gateway com sucesso."
  }
}

refundChannel: "api" confirma que o estorno saiu pelo adquirente na hora. Leia esse campo: se ele voltar diferente, o dinheiro ainda não saiu e o caso precisa de acompanhamento manual.

Aprovar é irreversível e tira dinheiro do seu saldo imediatamente. Não há rota de desfazer.

3. Recuse

curl -s -X POST https://api.ephra.io/v1/refund-requests/48127/reject \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Prazo de garantia de 7 dias encerrado e o curso foi assistido por completo."}'

{
  "success": true,
  "data": {
    "id": 48127,
    "status": "rejected",
    "message": "Solicitação de reembolso rejeitada."
  }
}

A reason da recusa vai para o comprador. Escreva uma frase que você defenderia numa reclamação — ela é o seu argumento se o caso virar contestação de cartão. Um id que não existe (ou que é de outra empresa) responde 404:

{ "success": false, "message": "Solicitação de reembolso não encontrada." }

4. Exporte o histórico

curl -s "https://api.ephra.io/v1/refund-requests/export?status=approved&startDate=2026-08-01T00:00:00.000Z&endDate=2026-08-31T23:59:59.000Z" \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": {
    "filename": "reembolsos-2026-09-12.xlsx",
    "base64": "UEsDBAoAAAAIAIMzLF2R28AJWQEAAPAEAAATAAAAW0NvbnRlbnRfVHlwZXNdLnhtbK2U...",
    "total": 0,
    "truncated": false
  }
}

Diferente da exportação de vendas, aqui o arquivo é XLSX em base64 — decodifique antes de gravar:

curl -s "https://api.ephra.io/v1/refund-requests/export?status=approved" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '.data.base64' | base64 -d > reembolsos.xlsx

truncated: true avisa que o recorte estourou o limite do arquivo: aperte o intervalo de datas e exporte em partes.

5. Entenda por que pediram

Antes de abrir a solicitação, o comprador responde um quiz de retenção. As respostas dizem se o problema é o produto, a entrega ou a expectativa de venda.

curl -s "https://api.ephra.io/v1/refund-quiz-attempts?page=1&pageSize=5&onlyCompleted=true" \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": [],
  "pagination": { "page": 1, "pageSize": 5, "total": 0, "totalPages": 0 }
}

onlyCompleted=true descarta quem abandonou o quiz no meio — normalmente quem desistiu de pedir o reembolso.

6. Acompanhe as contestações

Contestação (chargeback ou MED do Pix) é diferente de reembolso: quem abre é o banco do comprador, e o dinheiro sai com ou sem a sua concordância.

curl -s "https://api.ephra.io/v1/infractions?page=1&pageSize=5" \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": [],
  "pagination": { "page": 1, "pageSize": 5, "total": 0, "totalPages": 0 }
}

O evento em tempo real equivalente é infraction. Aprovar um reembolso antes que a contestação avance costuma sair mais barato do que perdê-la.

Todas as operações do domínio

Solicitações

A fila, com todos os filtros.

Aprovar e recusar

As duas decisões, cada uma com o seu motivo.

Quiz de retenção

O que o comprador respondeu antes de pedir.

Contestações

Chargebacks e MEDs abertos contra a empresa.

Integração

API do vendedor

Cobranças

Assinaturas

Ajuda

1. Leia a fila

2. Aprove

3. Recuse

4. Exporte o histórico

5. Entenda por que pediram

6. Acompanhe as contestações

Todas as operações do domínio

Solicitações

Aprovar e recusar

Quiz de retenção

Contestações

​1. Leia a fila

​2. Aprove

​3. Recuse

​4. Exporte o histórico

​5. Entenda por que pediram

​6. Acompanhe as contestações

​Todas as operações do domínio

Solicitações

Aprovar e recusar

Quiz de retenção

Contestações

1. Leia a fila

2. Aprove

3. Recuse

4. Exporte o histórico

5. Entenda por que pediram

6. Acompanhe as contestações

Todas as operações do domínio