API VyvaPay

Referência REST v1 para cobranças PIX, saques e consulta de transações. Todas as rotas usam JSON e autenticação por API Key.

Base: https://server.vyvapay.com

Visão geral

A API segue convenções REST: recursos em caminhos versionados (/api/v1), corpo e respostas em application/json, e códigos HTTP semânticos. Utilize HTTPS em produção.

Gere e revogue chaves no painel. Nunca exponha sk_live_... em aplicativos móveis ou repositórios públicos.

Pacote para integrar em outro sistema (README + instruções para IA)

Arquivos Markdown estáticos: /docs/README.md, /docs/AI_INTEGRATION.md. No repositório Git ficam em docs/ na raiz do projeto vyvapay.com (copie a pasta inteira).

Autenticação

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

Authorization: Bearer sk_live_...

Criar pagamento PIX

POST/api/v1/payments

Cria um pedido e retorna dados PIX (copia e cola e QR Code em Base64) para o pagador concluir a transação.

Corpo (JSON)

Campo	Tipo	Obrigatório	Descrição
amount	number	Sim	Valor em reais (positivo).
customer_email	string	Sim	E-mail do pagador.
customer_name	string	Não	Nome exibido na cobrança.
customer_cpf	string	Não	CPF do pagador (apenas dígitos ou formatado).
description	string	Não	Descrição da cobrança.
payment_method	"PIX"	Não	Padrão PIX.

Respostas

Código	Descrição
201	Cobrança criada.
400	Validação (corpo inválido).
401	API Key inválida.
500	Erro interno.

Requisição

const API_KEY = "sk_live_..." as const;

const res = await fetch("https://server.vyvapay.com/api/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 50,
    customer_email: "cliente@email.com",
    customer_name: "Ana Souza",
    customer_cpf: "12345678909",
    description: "Pedido #1024",
    payment_method: "PIX",
  } satisfies Record<string, unknown>),
});

if (!res.ok) throw new Error(await res.text());
const data = (await res.json()) as {
  id: string;
  pix_copy_paste: string | null;
};

Resposta

{
  "id": "65f1a2c8e4b0b21d4c9a0001",
  "order_id": "65f1a2c8e4b0b21d4c9a0002",
  "amount": 50,
  "status": "pending",
  "pix_copy_paste": "00020126...",
  "pix_qr_code_base64": "iVBORw0KGgo...",
  "expires_at": "2026-04-30T15:30:00.000Z"
}

Criar saque PIX

POST/api/v1/withdrawals

Inicia uma transferência PIX da sua conta para a chave informada.

Corpo (JSON)

Campo	Tipo	Obrigatório	Descrição
amount	number	Sim	Valor do saque.
pix_key	string	Sim	Chave PIX de destino.
key_type	enum	Sim	CPF, EMAIL, CNPJ, PHONE ou EVP.
description	string	Não	Referência interna.
document	string	Não	Documento do titular quando aplicável.

Respostas

Código	Descrição
201	Saque registrado.
400	Validação.
401	API Key inválida.
500	Erro interno.

Requisição

const API_KEY = "sk_live_..." as const;

const res = await fetch("https://server.vyvapay.com/api/v1/withdrawals", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 120.5,
    pix_key: "cliente@email.com",
    key_type: "EMAIL",
    description: "Repasse semanal",
    document: "12345678909",
  }),
});

const data = await res.json();

Resposta

{
  "id": "65f1a2c8e4b0b21d4c9a0101",
  "amount": 120.5,
  "status": "pending",
  "gateway_response": {}
}

Consultar transação

GET/api/v1/transactions/:id

Retorna uma transação do razão vinculada à sua conta, incluindo status do pagamento e dados do cliente quando disponíveis.

Parâmetros de rota

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador da transação (ledger).

Respostas

Código	Descrição
200	Encontrada.
401	API Key inválida.
404	Não encontrada.
500	Erro interno.

Requisição

const API_KEY = "sk_live_..." as const;
const id = "65f1a2c8e4b0b21d4c9a0001";

const res = await fetch(`https://server.vyvapay.com/api/v1/transactions/${id}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
if (!res.ok) throw new Error(await res.text());
const data = await res.json();

Resposta

{
  "id": "65f1a2c8e4b0b21d4c9a0001",
  "amount": 50,
  "type": "CREDIT",
  "status": "APPROVED",
  "created_at": "2026-04-30T14:00:00.000Z",
  "processed_at": "2026-04-30T14:01:20.000Z",
  "customer": {
    "id": "cliente@email.com",
    "name": "Ana Souza",
    "email": "cliente@email.com"
  },
  "description": "API Payment",
  "metadata": null
}

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.

Campo	Tipo	Obrigatório	Descrição
Content-Type	header	Sim	application/json
X-VyvaPay-Timestamp	header	Sim	Unix timestamp em segundos (string) usado na assinatura.
X-VyvaPay-Signature	header	Sim	HMAC SHA-256 em hexadecimal: assina a mensagem timestamp + "." + corpo bruto (UTF-8), usando o segredo do endpoint (whsec_…).
X-VyvaPay-Event-Id	header	Sim	Id do evento (coincide com o campo id no JSON).
X-VyvaPay-Endpoint-Id	header	Sim	Identificador do endpoint configurado no painel.

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.