Bibliotecas
SDKs VamPay
Integre a VamPay em JavaScript, TypeScript, Python, PHP ou Go com poucas linhas: criar cobrança PIX, consultar, sacar e validar webhooks, tudo já tipado e tratado.
Como funciona
Cada SDK é um arquivo único, sem dependências. Você baixa, coloca no seu projeto e importa. Eles ainda não estão publicados no npm, PyPI, Packagist ou pkg.go.dev, então não existe npm install nem pip install da VamPay.
Escolha a linguagem
Node 18 ou mais novo (usa o fetch nativo). Funciona também no Bun e no Deno.
Instalação
# 1. baixe o arquivo (vampay.ts ou vampay.mjs) e coloque na pasta do seu projeto
# 2. guarde a chave em variável de ambiente, nunca no código
export VAMPAY_API_KEY="vampay_sua_api_key"Criar uma cobrança PIX
import { VamPay } from './vampay' // no JavaScript: './vampay.mjs'
const vampay = new VamPay({ apiKey: process.env.VAMPAY_API_KEY! })
const pix = await vampay.createPayment(49.9, {
description: 'Pedido #123',
externalReference: 'pedido-123', // volta na consulta e nos webhooks
feeToCustomer: false,
})
console.log(pix.copyPaste) // PIX copia e cola
console.log(pix.paymentLink) // página de pagamento prontaConsultar e esperar o pagamento
// consulta uma vez
const status = await vampay.getPayment(pix.transactionId)
console.log(status.status) // PENDING | COMPLETED | EXPIRED | FAILED | CANCELLED
// ou espera sair de PENDING (consulta a cada 3 segundos)
const final = await vampay.waitForPayment(pix.transactionId)
if (final.status === 'COMPLETED') console.log('Pago!')O jeito recomendado de saber que o cliente pagou é o webhook (abaixo). A espera por consulta serve pra testes e scripts simples.
Receber webhooks
import express from 'express'
import { VamPay } from './vampay'
const app = express()
// o corpo precisa chegar BRUTO, sem passar por express.json()
app.post('/webhooks/vampay', express.raw({ type: 'application/json' }), (req, res) => {
try {
const event = VamPay.parseWebhook(
req.body.toString('utf8'),
req.header('X-vp-Signature') ?? '',
process.env.VAMPAY_WEBHOOK_SECRET!,
)
if (event.event === 'transaction.completed') {
// libere o pedido
}
res.sendStatus(200)
} catch {
res.sendStatus(401) // assinatura inválida
}
})A VamPay assina cada entrega com HMAC-SHA256 no header X-vp-Signature. Use o secret do webhook ou, se você não definiu um, a sua API Key. Os eventos e o formato estão em Webhooks.
Os mesmos métodos em todas as linguagens
| O que faz | JS / TS | Python | PHP | Go |
|---|---|---|---|---|
| Criar cobrança PIX | createPayment | create_payment | createPayment | CreatePayment |
| Consultar cobrança | getPayment | get_payment | getPayment | GetPayment |
| Esperar o pagamento | waitForPayment | wait_for_payment | waitForPayment | WaitForPayment |
| Listar cobranças | listPayments | list_payments | listPayments | ListPayments |
| Consultar taxas | getFees | get_fees | getFees | GetFees |
| Consultar saldo | getBalance | get_balance | getBalance | GetBalance |
| Saque via PIX | withdraw | withdraw | withdraw | Withdraw |
| Transferência interna | transfer | transfer | transfer | Transfer |
| Validar webhook | VamPay.verifyWebhook | VamPay.verify_webhook | VamPay::verifyWebhook | VerifyWebhook |
Erros
Quando a API responde com erro (valor inválido, chave errada, limite de requisições), o SDK lança VamPayError (no PHP, VamPayException; no Go, o erro devolvido é do tipo *vampay.Error) com a mensagem da API e o status HTTP. Falha de conexão ou tempo esgotado vêm com status 0.
Segurança
- Use o SDK sempre no servidor. A API Key nunca pode ir pro navegador ou pro app do cliente.
- Guarde a chave em variável de ambiente e teste antes no modo Sandbox.
- Baixe os arquivos só daqui (vampay.com.br/sdk) e confira o conteúdo antes de colocar no projeto.
