VamPay
VamPay

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

Instalaçãobash
# 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

criar-cobranca.tstypescript
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 pronta

Consultar e esperar o pagamento

consultar.tstypescript
// 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

webhook.tstypescript
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 fazJS / TSPythonPHPGo
Criar cobrança PIXcreatePaymentcreate_paymentcreatePaymentCreatePayment
Consultar cobrançagetPaymentget_paymentgetPaymentGetPayment
Esperar o pagamentowaitForPaymentwait_for_paymentwaitForPaymentWaitForPayment
Listar cobrançaslistPaymentslist_paymentslistPaymentsListPayments
Consultar taxasgetFeesget_feesgetFeesGetFees
Consultar saldogetBalanceget_balancegetBalanceGetBalance
Saque via PIXwithdrawwithdrawwithdrawWithdraw
Transferência internatransfertransfertransferTransfer
Validar webhookVamPay.verifyWebhookVamPay.verify_webhookVamPay::verifyWebhookVerifyWebhook

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.