Refunds

Uma devolução (refund) estorna, total ou parcialmente, uma cobrança paga. O crédito do pagamento na sua wallet é revertido proporcionalmente (incluindo a taxa).

Refund exige KYC aprovado

Criar devoluções é uma operação de saída de dinheiro — exige a conta com KYC aprovado. Uma conta com KYC pendente recebe 403 KYC_REQUIRED.

Criar uma devolução

POST /v1/refunds — exige o scope refunds:create e o header Idempotency-Key (obrigatório). O amount é uma string em reais; se ausente, estorna o saldo restante (devolução total).

curl

curl -X POST https://api.vmixpay.com.br/v1/refunds \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Idempotency-Key: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Content-Type: application/json" \
  -d '{
    "charge_id": "9b2f1c7a-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
    "amount": "199.90",
    "reason": "pedido cancelado"
  }'

Node.js

import { randomUUID } from "node:crypto";

const res = await fetch("https://api.vmixpay.com.br/v1/refunds", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    charge_id: "9b2f1c7a-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
    amount: "199.90", // omita para estornar o saldo restante (total)
    reason: "pedido cancelado",
  }),
});

const refund = await res.json();

Resposta 201 (novo) ou 200 (replay com a mesma Idempotency-Key):

{
  "refund_id": "4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
  "charge_id": "9b2f1c7a-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
  "account_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "amount": "199.90",
  "status": "completed",
  "reason": "pedido cancelado",
  "created_at": "2026-06-22T12:05:00.000Z"
}

Total vs. parcial

• Total (sem amount, ou amount = saldo restante): a cobrança vira refunded.
• Parcial (amount ≤ saldo restante): a cobrança continua paid. Um parcial posterior que zere o saldo a leva a refunded.

Erros

HTTP	Código	Quando
400	IDEMPOTENCY_KEY_REQUIRED	Header Idempotency-Key ausente.
409	IDEMPOTENCY_KEY_REUSED	Mesma chave com corpo diferente.
409	CHARGE_NOT_REFUNDABLE	Cobrança não-paga ou já totalmente refunded.
422	REFUND_EXCEEDS	O valor excede o saldo restante numa cobrança ainda paid.
404	CHARGE_NOT_FOUND	Cobrança inexistente ou de outro merchant (genérico).
403	KYC_REQUIRED	Conta sem KYC aprovado.
403	—	Token sem o scope refunds:create.
502	BANK_UNAVAILABLE	O banco falhou; o estorno fica failed e é re-tentável.

409 vs. 422

Esgotar o saldo de uma cobrança a leva a refunded; um próximo refund nela recebe 409 CHARGE_NOT_REFUNDABLE (não 422). O 422 REFUND_EXCEEDS só ocorre quando a cobrança ainda está paid e o valor pedido excede o saldo — o check de status precede o de saldo.

Consultar uma devolução

GET /v1/refunds/{refund_id} — devolve a mesma projeção da criação.

O GET usa payments:read, não refunds:create

A consulta de refund exige o scope payments:read — não há scope refunds:read dedicado. Um client que só tenha refunds:create recebe 403 aqui. Um refund de outro merchant retorna 404 REFUND_NOT_FOUND (tenant-safe).

curl https://api.vmixpay.com.br/v1/refunds/4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"  # scope payments:read