API VyvaPay

Autenticação

Inclua o cabeçalho Authorization com o valor Bearer SUA_CHAVE. Requisições sem chave válida recebem 401.

Geolocalização do cliente

Para análise antifraude e auditoria, você pode (e deve) enviar o IP e a localização do usuário final que solicitou o pagamento ou saque dentro do seu app — não o IP do servidor que chama nossa API. Os campos abaixo são opcionais em /api/v1/payments e /api/v1/withdrawals e ficam visíveis no detalhe da transação no painel.

Apps na Vercel (Next.js)

A Vercel injeta automaticamente headers x-vercel-ip-* em todas as requisições recebidas pelo seu Edge / Functions. Em uma Server Action ou Route Handler, leia esses headers e repasse no body para a VyvaPay:

import { headers } from "next/headers";

export async function POST(request: Request) {
  const h = await headers();
  const xff = h.get("x-forwarded-for");
  const ip = xff?.split(",")[0]?.trim() ?? h.get("x-real-ip") ?? null;

  const res = await fetch("https://server.vyvapay.com/api/v1/payments", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VYVAPAY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 50,
      customer_email: "cliente@email.com",
      ip_address: ip,
      ip_country: h.get("x-vercel-ip-country"),
      ip_region: h.get("x-vercel-ip-country-region"),
      ip_city: h.get("x-vercel-ip-city")
        ? decodeURIComponent(h.get("x-vercel-ip-city")!)
        : null,
      ip_postal_code: h.get("x-vercel-ip-postal-code"),
      ip_latitude: h.get("x-vercel-ip-latitude"),
      ip_longitude: h.get("x-vercel-ip-longitude"),
      ip_timezone: h.get("x-vercel-ip-timezone"),
    }),
  });

  return Response.json(await res.json());
}

Apps em Cloudflare / Fly / outros

Cloudflare expõe CF-Connecting-IP e CF-IPCountry, e o objeto request.cf traz city, region, latitude, longitude, timezone e postalCode. Em outros provedores, use x-forwarded-for e qualquer serviço de geo-IP da sua escolha.

Se você não enviar nenhum desses campos, a VyvaPay registra apenas o IP do remetente HTTP (que normalmente é o seu servidor). Se a VyvaPay receber a chamada diretamente via Vercel/Cloudflare (ex: dashboard interno), os headers do edge são lidos automaticamente como fallback.

Webhooks de eventos (painel)

No dashboard, em Modo Dev → Webhooks, você cadastra endpoints HTTPS que recebem notificações quando eventos ocorrem na conta (pagamentos, pedidos, saques, etc.).

Requisitos do endpoint

• HTTPS obrigatório.
• Responda com 200 ou 201 para confirmar entrega. Qualquer outro código ou erro de rede conta como falha.
• Entregas com falha são repetidas automaticamente até 4 tentativas, com espera de 30s, depois 1 min, depois 5 min entre uma tentativa e a seguinte. Após esgotar as tentativas, o painel marca a entrega como falha; você pode reenfileirar manualmente na aba Entregas.

Corpo e cabeçalhos

Cada notificação é um POST com corpo JSON contendo id, type, created_at e data.

Para validar: calcule o HMAC-SHA-256 em hexadecimal do segredo do endpoint sobre a mensagem formada por timestamp + "." + corpo_bruto (UTF-8, bytes exatamente como recebidos) e compare com X-VyvaPay-Signature. Use o mesmo timestamp do cabeçalho X-VyvaPay-Timestamp.

Webhooks do gateway de liquidação (internos) seguem outro fluxo; esta seção refere-se apenas aos webhooks de eventos que você configura no painel VyvaPay.