Referência da API

Estornar transação

Temporariamente indisponível pela API. Enquanto durar a revisão do fluxo de estorno, este endpoint responde 403 para todas as chaves, mesmo com a permissão createRefund. Para estornar uma transação, abra um chamado no suporte informando o transactionId; a equipe executa o estorno pelo painel interno e o webhook cashin.refunded é disparado normalmente. Quando reativado: estorna uma transação aprovada. Estornos PIX devolvem o valor integral ao pagador imediatamente. Estornos de cartão de crédito são iniciados via adquirente e podem levar até 30 dias úteis para aparecer no extrato do titular.

POST/transactions/refund/:transactionId

Endpoint desativado temporariamente

transactionId Toda chamada retorna 403 Refunds via API are temporarily disabled. Solicite o estorno pelo suporte. Quando o endpoint voltar, lembre: uma vez iniciado, um estorno não pode ser cancelado — confira o ID e o valor antes de chamar em produção.

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

transactionIdstring (path)obrigatório

ID interno da transação a estornar. Apenas transações com status APPROVED podem ser estornadas.

Exemplo: 1234567

Respostas

200

Estorno iniciado.

JSON

{
  "id": "17913320791467683016950003",
  "status": "REFUNDED",
  "refundedAt": "2026-04-08T16:45:21.501Z",
  "message": "Transaction refunded successfully"
}

400

A transação não está em estado estornável (já estornada, nunca aprovada, em chargeback ou marcada como INCOSISTENT).

JSON

{
  "statusCode": 400,
  "message": "Transaction is not in APPROVED status"
}

403

Estorno pela API desativado temporariamente (resposta atual para todas as chaves), ou API key sem a permissão createRefund.

JSON

{
  "statusCode": 403,
  "message": "Refunds via API are temporarily disabled. Request the refund through support."
}

404

Transação não encontrada.

JSON

{ "statusCode": 404, "message": "Transaction not found" }

Exemplos

cURL

curl -X POST "https://api.ihubplay.com/transactions/refund/1234567" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"

JavaScript

const token = Buffer.from("secret:" + process.env.IHUBGAMES_SECRET_KEY).toString("base64");

const res = await fetch("https://api.ihubplay.com/transactions/refund/1234567", {
  method: "POST",
  headers: { Authorization: `Basic ${token}` },
});

const traceId = res.headers.get("x-trace-id");
const result = await res.json();

if (res.ok) {
  console.log("estornada em:", result.refundedAt);
} else {
  console.error(`falha no estorno: ${result.message} (trace: ${traceId})`);
}