api.vouchereto.com/v1

Desenvolva com a API do Vouchereto

Uma API REST enxuta com uma única função: receber um voucher, bloqueá-lo para um cliente e transformá-lo em saldo na sua plataforma.

Solicitar acesso ao sandbox Ler a documentação Referência completa

URL base: api.vouchereto.com/v1
Teste e produção: Chaves vch_test_… e vch_live_…
Autenticação: Chave Bearer + HMAC-SHA256
Formato: JSON · valores em unidades menores

Seu primeiro resgate

Obtenha suas chaves
Crie uma chave de teste no portal de empresas. Você vê a chave completa uma única vez; a parte final dela também é o segredo com que você assina as requisições.
Reserve o voucher
Envie o código, a moeda e a referência do seu cliente. O voucher fica bloqueado para esse cliente e não pode ser usado em nenhum outro lugar.
Credite e depois capture
Credite o saldo do seu lado e depois faça a captura. Se a recarga falhar, cancele em vez disso e o voucher é liberado.
Escute os webhooks
Registre um endpoint para receber eventos assinados de capturas, cancelamentos, expirações e checkouts.

Resgates · exemplo

POST /v1/redemptions
Authorization: Bearer vch_test_…
Idempotency-Key: topup-88213
Vouchereto-Signature: t=1790500000,v1=9c1e5f07…
Content-Type: application/json

{ "code": "7K2M-9QXR-4HTB-2WNZ", "customer_ref": "acct_48213", "currency": "USD" }

# 201 Created
{ "id": "5f0c2a7e-…", "object": "redemption", "status": "reserved",
  "amount_minor": 5000, "currency": "USD", "voucher_last4": "2WNZ",
  "customer_ref": "acct_48213", "livemode": false,
  "expires_at": "2026-09-27T14:12:00Z", "captured_at": null }

# Credit the customer first, then capture. Irreversible.
POST /v1/redemptions/5f0c2a7e-…/capture
Authorization: Bearer vch_test_…
Idempotency-Key: topup-88213-capture
Vouchereto-Signature: t=1790500012,v1=4b7d2e91…

# 200 OK
{ "id": "5f0c2a7e-…", "object": "redemption", "status": "captured",
  "captured_at": "2026-09-27T14:02:31Z", … }

# The top-up failed: release the voucher back to the customer
POST /v1/redemptions/5f0c2a7e-…/cancel
Authorization: Bearer vch_test_…
Idempotency-Key: topup-88213-cancel
Vouchereto-Signature: t=1790500015,v1=77aa01c3…

# 200 OK
{ "id": "5f0c2a7e-…", "object": "redemption", "status": "cancelled", … }

// Vouchereto-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + "." + rawBody)>
// secret = the whsec_… signing secret of your webhook endpoint
import crypto from "node:crypto";

export function verifyWebhook(rawBody, header, secret) {
  const parts = header.split(",").map((p) => p.trim().split("="));
  const t = Number(parts.find(([k]) => k === "t")?.[1]);
  const sigs = parts.filter(([k]) => k === "v1").map(([, v]) => Buffer.from(v, "hex"));
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return sigs.some((s) => s.length === expected.length && crypto.timingSafeEqual(s, expected));
}

O ciclo de vida de um resgate

voucher ativoreservado

capturadoO voucher foi usado. Irreversível.
canceladoVocê cancelou. O voucher volta a ficar ativo.
reserva expiradaNão foi capturado a tempo (15 minutos por padrão). O voucher volta a ficar ativo.

Referência para a integração

Assinatura das requisições

Toda requisição leva um cabeçalho Vouchereto-Signature: um timestamp e um HMAC-SHA256 do timestamp, do método, do caminho e do corpo, gerado com o segredo da sua chave de API. Aceitamos uma diferença de relógio de até 300 segundos.

sign.js

// Sign every request with the secret part of your API key (the text after the last "_")
const t = Math.floor(Date.now() / 1000);
const payload = `${t}.${method} ${pathWithQuery}\n${body}`;
const v1 = crypto.createHmac("sha256", keySecret).update(payload).digest("hex");
headers["Vouchereto-Signature"] = `t=${t},v1=${v1}`;

Idempotência

Todo POST exige um cabeçalho Idempotency-Key. Repita uma requisição com a mesma chave e você recebe a resposta original, marcada com Idempotent-Replayed: true. As chaves são guardadas por pelo menos 30 dias.

Vouchers de sandbox

Com uma chave de teste, POST /v1/sandbox/vouchers cria um voucher de teste no estado que você pedir (active, reserved, redeemed, expired, risk_hold ou void) e retorna o código dele. As chaves de teste só enxergam dados de teste.

Eventos de webhook

Eventos que enviamos para o seu endpoint
Evento	Quando é enviado
redemption.captured	Um voucher reservado foi capturado. Pode manter o saldo creditado com segurança.
redemption.cancelled	Uma reserva foi cancelada. O voucher volta a ficar ativo.
redemption.expired	Uma reserva expirou sem captura.
checkout.completed	Um checkout hospedado foi pago e o voucher aplicado.
checkout.expired	Uma sessão de checkout hospedado expirou sem pagamento.
checkout.failed	Um checkout pago foi revertido, por exemplo após um reembolso.

Erros

Códigos de erro e o que dizer ao cliente
Status	Código	O que dizer ao cliente
404	VOUCHER_INVALID	Não encontramos esse código. Confira e tente novamente.
409	VOUCHER_ALREADY_REDEEMED	Este voucher já foi usado.
409	VOUCHER_RESERVED	Este voucher está sendo usado em outro pagamento neste momento.
422	VOUCHER_EXPIRED	Este voucher expirou.
422	UNIVERSAL_NOT_ACCEPTED	Não aceitamos vouchers universais. Use um voucher deste site.
422	CURRENCY_MISMATCH	Este voucher está em outra moeda.
429	TOO_MANY_INVALID_ATTEMPTS	Muitas tentativas. Aguarde alguns minutos e tente novamente.

Os erros seguem a RFC 7807 (application/problem+json), com um código estável e um request_id.

Esta página resume a API. A referência completa, com todos os campos, está publicada em www.vouchereto.com/docs/reference.

Travou em alguma coisa?

Escreva para [DEVELOPER SUPPORT EMAIL]. Um desenvolvedor lê cada mensagem.