Reembolsos

Um Refund é uma entidade de primeira classe, não uma flag no Order. Você pode emitir reembolsos parciais, vários reembolsos contra o mesmo Order, ou reembolso + nova cobrança no mesmo fluxo.

Duas formas pelas quais o registro de reembolso pode passar a existir:

O fluxo iniciado pelo cliente usa um token de pedido de reembolso de curta duração. Você cria um token (B2B ou dashboard), entrega a URL para o comprador como preferir, e o comprador completa os detalhes do reembolso em checkout.infraio.xyz/refund-request/:token. O comprador nunca toca na sua API e nunca vê a sua chave de lojista.

Ciclo de vida do reembolso

Iniciado pelo lojista

Você decide reembolsar (por exemplo, o comprador reclamou no chat). Chame o endpoint de iniciado-pelo-lojista — ele pula a revisão e cai em APPROVED imediatamente.

POST /b2b/v1/merchants/{merchant_id}/refunds
{
  "order_id": "ord_01J5K…",
  "amount": "49.00",                       // parcial ou total, na moeda de exibição do pedido
  "reason": "customer complaint #4521",
  "refund_to_address":   "0xBUYER…",       // obrigatório para trilhos cripto
  "refund_network":      "polygon",        // slug da rede; veja Conceitos → Redes
  "refund_token_address":"0xUSDC_CONTRACT" // contrato ERC-20 devolvido; geralmente o token original
}

Não há campo currency na requisição de reembolso — reembolsos sempre herdam a moeda de exibição do pedido (USD hoje). O trio (refund_to_address, refund_network, refund_token_address) é o destino on-chain. São ignorados para trilhos fiat (roteamento automático pelo provedor).

O pedido mantém o status atual até você executar a transferência on-chain (veja Executando um reembolso cripto).

Iniciado pelo cliente — tokens de pedido de reembolso

O comprador preenche o formulário de reembolso na nossa página hospedada, não na sua. O seu único trabalho é criar um token e entregar a URL.

Ciclo de vida do token

Padrões de TTL

Você pode sobrescrever o padrão com o campo ttl_seconds no body. Nenhum mínimo ou máximo é aplicado; valores comuns vão de 1 minuto a 7 dias.

Criação via API B2B

Para backends que querem gerar um link de reembolso programaticamente logo após uma conversa de suporte, um fluxo de cancelamento de pedido, etc.

POST /b2b/v1/merchants/{merchant_id}/refund-requests
Content-Type: application/json
X-Client-ID: pk_live_…
X-Timestamp: 1729536000
X-Signature: 4f2a1b9c8d3e2f1a0b9c8d7e6f5a4b3c…
 
{
  "ref_type":    "order_id",                          // obrigatório: order_id | order_number | session_id | session_key
  "ref_value":   "ord_01J5K…",                        // obrigatório: combina com ref_type
  "amount":      "49.00",                             // obrigatório — trava o máximo que o comprador pode submeter
  "ttl_seconds": 1800,                                // opcional — padrão de 1800 (30 min)
  "metadata":    { "support_ticket": "4521" },        // opcional — chave/valor estilo Stripe
  "hide_summary": false,                              // flags opcionais de UI para o formulário hospedado
  "hide_header":  false
}

O valor está no body de criação e é obrigatório. Ele trava o teto que o comprador pode submeter no formulário — ele pode submeter por menos, nunca por mais. (Para reembolsos parciais, crie um token com o valor parcial; para reembolsos totais, crie com o total do pedido.)

O formato mais antigo { "order_id": "..." } ainda é aceito e é tratado como ref_type=order_id, mas integrações novas devem usar o par explícito ref_type + ref_value.

Resposta:

{
  "token":      "rfqt_01J7P3Q9R…",
  "refund_url": "https://checkout.infraio.xyz/refund-request/rfqt_01J7P3Q9R…",
  "expires_at": "2026-05-28T10:32:00Z"
}

Dispara refund_request.created para os seus endpoints de webhook (para você poder logar / auditar qual token está ativo no momento para um pedido).

Criação via dashboard

O modal Issue Refund no dashboard do lojista  expõe um toggle: Execute now vs Send link to customer. Escolher o segundo cria um token de pedido de reembolso (igual à chamada B2B acima) e mostra para você a URL com um botão de copiar e um QR code. Cole no canal que fizer sentido — e-mail, chat de suporte, SMS.

Via o SDK JavaScript — openRefundRequest

Se você já tem @lartech/infraio-checkout-js na sua stack e quer que o comprador complete o reembolso dentro do fluxo da sua página (e não via URL externa), combine a criação B2B com sdk.openRefundRequest():

// Lado do servidor: cria o token
const { token } = await fetch("/api/mint-refund-token", { method: "POST" }).then(r => r.json());
 
// Lado do cliente: abre o formulário hospedado
const sdk = await loadInfraIo("pk_live_yourkeyhere");
const close = sdk.openRefundRequest({
  token,
  mode: "popup",                       // ou "redirect" | "embed"
  onSuccess: ({ linkToken, refundId }) => {
    // linkToken → página de status /r/:linkToken para o comprador.
    // refundId  → referência da API B2B para aprovar / rejeitar.
    window.location.href = `/r/${linkToken}`;
  },
  onCancel: () => { /* comprador fechou o popup */ },
  onError:  (err) => { /* veja a referência do SDK */ },
});

Veja a referência do SDK → sdk.openRefundRequest() para a tabela completa de opções.

Renovação pelo cliente — re-emissão dirigida pelo comprador

Se o comprador abre a URL depois do token expirado, a página oferece um botão Pedir link novo no lugar do formulário. Clicar nele:

1. Envia o pedido de renovação (sem credenciais; o próprio link o autoriza)
2. Opcionalmente captura uma nota em texto livre (customer_note) que o comprador pode deixar para você
3. Move o token para RENEWAL_REQUESTED e dispara refund_request.renewal_requested para o seu webhook

Seu dashboard mostra um badge no widget de pedidos de renovação. Aprove (um clique) e um token ACTIVE novo é emitido, dispara refund_request.renewed e te deixa copiar a URL nova para enviar de novo. A URL antiga continua acessível, mas renderiza “Substituído — confira seu e-mail” para que uma cópia encaminhada da URL antiga não consiga pescar a nova.

Executando um reembolso cripto

A API registra a intenção — ela não move fundos. Você assina e transmite a transferência on-chain da carteira do seu lojista, e depois estampa o tx hash de volta no registro de reembolso:

POST /b2b/v1/refunds/:refund_id/submit-tx
Content-Type: application/json
 
{
  "tx_hash": "0xabcd…",
  "network": "ethereum",
  "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}

Os três campos do body são obrigatórios: o mesmo tx hash pode existir em redes diferentes, e você pode reembolsar em uma stablecoin diferente daquela em que o pagamento original foi capturado.

Quando a InfraIO Pay vê essa transação atingir a contagem de confirmações necessária (veja Redes e ativos), o reembolso vai para EXECUTED e o total reembolsado do Order é atualizado.

Reembolsos em TRON, Solana e TON

O fluxo é o mesmo: você envia o reembolso da sua própria carteira e depois envia o hash da transação. Os detalhes seguem a rede:

• A tela de reembolso no dashboard mostra o destino, o valor, a rede e o token, além de um QR code quando a rede oferece suporte: um QR do Solana Pay na Solana e um link de transferência TON na TON. Na TRON, mostra o endereço de destino para copiar (nenhum link de carteira carrega o valor), então informe o valor você mesmo.
• token_address é o endereço do token nessa rede: o contrato TRC-20, o mint SPL ou o endereço do Jetton master.
• Os formatos do hash da transação diferem: hex puro na TRON, uma assinatura base58 na Solana e um hash hex ou base64 na TON.
• A plataforma verifica essa transação exata on-chain e então move o reembolso para EXECUTED, usando as contagens de confirmação de Redes e ativos.

Eventos de webhook

O subsistema de reembolsos dispara duas famílias de eventos:

Ciclo de vida do token (refund_request.*)

Ciclo de vida do reembolso (payment.refund.*)

payment.failed não dispara para um reembolso — reembolsos têm a própria série de eventos com prefixo payment.refund.*.

Próximos passos

• Referência do SDK → sdk.openRefundRequest() — abre o formulário hospedado de reembolso como popup / redirect / embed.
• Referência da API → Reembolsos — catálogo de endpoints (criação, submit, renovação, status).
• Conceitos → Pedidos — como o estado do Refund liga de volta ao ciclo de vida do Order.
• Webhooks → Visão geral — catálogo completo de eventos.