VPN Pay — Documentação da API

Pública e somente leitura. Operações e dados continuam exigindo chave autenticada.

1. Visão geral
Tudo que um sistema externo precisa saber antes da primeira chamada.
ItemValor
Endereço basehttps://vpnpay.com.br/api/public/v1
AmbientesUm endereço por conta. A chave define se é chave de produção (vpnp_live_) ou de teste (vpnp_test_).
FormatoJSON em todas as chamadas e respostas (application/json; charset=utf-8).
ValoresSempre inteiros em centavos. R$ 12,34 = 1234. Nunca envie decimais.
MoedaCampo currency com 3 letras (padrão BRL).
Identificação da chamadaToda resposta traz request_id. Guarde-o para suporte.
VersãoA versão está no caminho (/v1). Campos novos podem ser adicionados sem aviso; ignore o que não conhecer.

Toda resposta usa o mesmo envelope:

envelope de sucesso
{
  "success": true,
  "data": { "id": "…", "object": "payment" },
  "error": null,
  "code": null,
  "message": null,
  "request_id": "0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"
}
envelope de erro
{
  "success": false,
  "data": null,
  "error": "invalid_request",
  "code": "invalid_request",
  "message": "Campo amount deve ser inteiro positivo em centavos",
  "request_id": "0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"
}
2. Autenticação
Chave de API no cabeçalho Authorization. O cliente é sempre identificado pela chave.
cabeçalhos
Authorization: Bearer vpnp_live_9f2a1c4d7b.5c1e…segredo
Content-Type: application/json

A chave tem duas partes separadas por ponto: prefixo e segredo. O segredo aparece uma única vez, na criação ou troca da chave. Nunca envie tenant_id no corpo: qualquer valor enviado é ignorado.

Permissão (scope)O que libera
payments:read / payments:writeConsultar / criar cobranças Pix
payouts:read / payouts:writeConsultar / solicitar repasses
refunds:read / refunds:writeConsultar / criar devoluções
recipients:read / recipients:writeConsultar / cadastrar recebedores
balances:readConsultar saldos
reconciliation:readConsultar conciliação
webhooks:manageGerenciar avisos automáticos
SituaçãoHTTPcode
Cabeçalho ausente, chave inválida, revogada ou expirada401unauthorized
Chave válida, mas sem o scope exigido pelo endpoint403forbidden
3. Idempotência
Obrigatória em POST /payments, POST /payouts e POST /refunds.
cabeçalho
Idempotency-Key: pedido-123-pagamento-1
  • Mínimo de 8 caracteres. Use algo derivado do seu pedido, não um valor aleatório por tentativa.
  • Mesma chave + mesmo corpo: devolve exatamente a mesma resposta, sem criar nova operação.
  • Mesma chave + corpo diferente: recusado com 409 idempotency_conflict.
  • Se a operação falhar, a chave é liberada e você pode repetir com o mesmo valor.
  • A chave é isolada por cliente e por endpoint.
4. Pagamentos (Pix In)
MétodoCaminhoScope
POST/paymentspayments:write
GET/paymentspayments:read
GET/payments/:idpayments:read
CampoTipoObrigatórioDescrição
amountinteiro (centavos)simValor da cobrança, maior que zero
currencystring(3)nãoPadrão BRL
payer.namestringsimNome de quem paga
payer.documentstringsimCPF ou CNPJ de quem paga
payer.emailstringnãoE-mail do pagador
merchant_iduuidnãoUnidade comercial da VPN Pay
recipient_iduuidnãoRecebedor do valor líquido; quando ausente, usa o recebedor principal da unidade
external_referencestringnãoSeu identificador do pedido
metadataobjetonãoDados livres do seu sistema (devolvidos na consulta)
provider_connection_iduuidnãoConexão específica do provedor
expires_in_minutesinteiro >= 5nãoValidade do Pix (padrão 60)

Smart Routing. Se provider_connection_id não for enviado, a VPN Pay escolhe automaticamente a conexão elegível conforme prioridade, custo e saúde do provedor. Se nenhuma conexão estiver elegível, a cobrança não é criada e a resposta explica o motivo.

request
curl -X POST https://vpnpay.com.br/api/public/v1/payments \
  -H "Authorization: Bearer $VPNPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042-pagamento-1" \
  -d '{
    "amount": 4990,
    "currency": "BRL",
    "merchant_id": "5f1f…",
    "external_reference": "pedido-1042",
    "expires_in_minutes": 30,
    "payer": { "name": "Maria Souza", "document": "12345678909", "email": "maria@exemplo.com" }
  }'
response 201
{
  "success": true,
  "data": {
    "id": "8f0c…",
    "object": "payment",
    "status": "PENDING",
    "amount": 4990,
    "currency": "BRL",
    "merchant_id": "5f1f…",
    "external_reference": "pedido-1042",
    "paid_at": null,
    "expires_at": "2026-09-12T22:30:00.000Z",
    "created_at": "2026-09-12T22:00:00.000Z",
    "br_code": "00020126…5204000053039865802BR…",
    "qr_code": "data:image/png;base64,iVBORw0K…",
    "provider_connection_id": "2f63…"
  },
  "error": null, "code": null, "message": null,
  "request_id": "…"
}

br_code é o copia e cola; qr_code é a imagem (base64 ou URL, conforme o provedor). Na consulta GET /payments/:id a resposta traz também charge (dados do provedor, incluindo taxa do provedor quando informada) e attempts (tentativas, com provedor e conexão usados).

5. Estados do pagamento
statusSignificado
CREATEDCobrança registrada, ainda sem Pix emitido
PENDINGPix emitido, aguardando pagamento
PROCESSINGProvedor processando a confirmação
PAIDPago e confirmado — só aqui libere o pedido
FAILEDFalha confirmada pelo provedor
CANCELEDCancelada antes do pagamento
EXPIREDPrazo do Pix vencido sem pagamento
UNKNOWNResposta sem confirmação; nunca trate como pago nem recrie a cobrança
RECONCILIATION_REQUIREDDivergência detectada; em conferência pela VPN Pay
6. Repasses (Pix Out)
MétodoCaminhoScope
POST/payoutspayouts:write
GET/payoutspayouts:read
GET/payouts/:idpayouts:read
CampoTipoObrigatório
recipient_iduuidsim
pix_key_iduuid (chave Pix ativa do recebedor)sim
amountinteiro (centavos)sim
currencystring(3)não (BRL)
merchant_iduuidnão
provider_connection_iduuidnão (Smart Routing quando ausente)
  • Só é possível repassar o saldo disponível do recebedor. O valor é reservado no momento do pedido e devolvido ao disponível se o repasse falhar.
  • Antes de qualquer chamada ao provedor, o monitoramento de risco é consultado. Se o recebedor estiver bloqueado, o repasse é registrado com status BLOCKED, o provedor não é acionado e nenhum saldo é reservado.
  • Estados: CREATED, PENDING, PROCESSING, DONE, FAILED, CANCELED, BLOCKED, UNKNOWN, RECONCILIATION_REQUIRED.
request
curl -X POST https://vpnpay.com.br/api/public/v1/payouts \
  -H "Authorization: Bearer $VPNPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: repasse-semana-38-loja-12" \
  -d '{ "recipient_id": "b3c1…", "pix_key_id": "77aa…", "amount": 25000 }'
7. Devoluções
MétodoCaminhoScope
POST/refundsrefunds:write
GET/refundsrefunds:read
GET/refunds/:idrefunds:read
CampoTipoObrigatórioDescrição
payment_iduuidsimPagamento pago que será devolvido
amountinteiro (centavos)simIgual ao pagamento = total; menor = parcial
reasonenumsimCUSTOMER_CANCEL_BEFORE_DISPATCH, CUSTOMER_CANCEL_AFTER_DISPATCH, MERCHANT_OUT_OF_STOCK, MERCHANT_CANCEL_AFTER_PICKUP, DRIVER_NO_SHOW, DRIVER_FAILURE, PLATFORM_ERROR, FRAUD, DUPLICATE_PAYMENT
liabilities[]listasimQuem assume o valor. A soma precisa ser igual a amount
liabilities[].partyenumsimMERCHANT, DRIVER, PARTNER, OTHER ou PLATFORM
liabilities[].amountinteirosimParcela assumida
liabilities[].recipient_iduuidcondicionalObrigatório quando party não é PLATFORM
notesstringnãoObservação interna
  • Vários estornos parciais no mesmo pagamento são permitidos até o total pago.
  • A devolução só é concluída após confirmação do provedor (valor e referência conferidos).
  • Divergência entre o que a VPN Pay registrou e o que o provedor confirmou não conclui a devolução: ela fica em RECONCILIATION_REQUIRED para conferência manual.
  • Estados: CREATED, PENDING, PROCESSING, DONE, FAILED, CANCELED, UNKNOWN, RECONCILIATION_REQUIRED.
request — devolução parcial
curl -X POST https://vpnpay.com.br/api/public/v1/refunds \
  -H "Authorization: Bearer $VPNPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042-devolucao-1" \
  -d '{
    "payment_id": "8f0c…",
    "amount": 1500,
    "reason": "MERCHANT_OUT_OF_STOCK",
    "liabilities": [ { "party": "MERCHANT", "amount": 1500, "recipient_id": "b3c1…" } ]
  }'
8. Recebedores
MétodoCaminhoScope
POST/recipientsrecipients:write
GET/recipientsrecipients:read
GET/recipients/:idrecipients:read
GET/recipients/:id/balancebalances:read
CampoTipoObrigatórioValidação
typeenumsimMERCHANT, DRIVER, PARTNER ou OTHER
legal_namestringsimNome/razão social
display_namestringnãoNome de exibição
document_typestringnãoCPF ou CNPJ
document_numberstringnãoValidado com dígito verificador; não pode repetir no mesmo cliente
emailstringnãoFormato de e-mail válido
phonestringnãoDDD + número
external_referencestringnãoSeu identificador

Chaves Pix e contas bancárias são cadastradas no console e entram como pendentes até conferência; a API nunca devolve a chave completa. O recebedor começa em PENDING e só recebe repasse quando estiver ACTIVE.

9. Saldos
MétodoCaminhoRetorno
GET/balancesSaldos do cliente por conta e moeda
GET/recipients/:id/balance?currency=BRLSaldo disponível do recebedor (em centavos)
TipoSignificado
AVAILABLEDisponível para repasse agora
PENDINGConfirmado, aguardando liberação
BLOCKEDRetido por risco, disputa ou decisão operacional
RECEIVABLEValor a receber, ainda não liquidado — não é sacável

Importante: só AVAILABLE pode virar repasse. RECEIVABLE é expectativa de recebimento e nunca é sacável.

10. Conciliação (somente leitura)
MétodoCaminhoScope
GET/reconciliationreconciliation:read
GET/reconciliation/:idreconciliation:read

A listagem traz as execuções de conciliação; o detalhe traz o resultado por item, com o estado da comparação (conferido, divergente, ausente no provedor). Não há escrita por API.

11. Entregas com parceiro logístico
O custo da entrega sai do dinheiro do próprio pedido daquela loja. Não existe carteira, saldo editável nem adiantamento da VPN Pay.
MétodoCaminhoScope
GET/deliveries?limit=20delivery:read
GET/deliveries/:iddelivery:read
POST/deliveries/quotesdelivery:write
POST/deliveries/:id/fundingdelivery:write
POST/deliveries/:id/dispatchdelivery:write
POST/deliveries/:id/canceldelivery:write

A) Cotar — cria a solicitação e devolve a cotação (dois modos)

Pré-checkout — cote o frete antes de criar a cobrança, porque ele compõe o total cobrado do cliente. A cotação pré-checkout não reserva saldo, não cria custeio e não permite despacho. Crie a cobrança com o mesmo external_reference e o mesmo merchant_id, somando data.quote.total ao pedido, e custeie antes de data.quote.expires_at.

request — pré-checkout
curl -X POST https://vpnpay.com.br/api/public/v1/deliveries/quotes \
  -H "Authorization: Bearer $VPNPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1043-cotacao-1" \
  -d '{
    "merchant_id": "3c1d…",
    "external_reference": "pedido-1043",
    "dropoff": {
      "address": {
        "street": "Rua Cameron", "number": "66", "district": "Miguel Couto",
        "city": "Nova Iguaçu", "state": "RJ", "postalCode": "26070482"
      },
      "contact": { "name": "Diogo", "phone": "+5521994977331", "instructions": "" }
    }
  }'

Legado — o pedido já existe e define a unidade e o dinheiro:

request — legado
curl -X POST https://vpnpay.com.br/api/public/v1/deliveries/quotes \
  -H "Authorization: Bearer $VPNPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042-cotacao-1" \
  -d '{
    "payment_id": "8f0c…",
    "external_reference": "pedido-1042",
    "dropoff": {
      "address": {
        "street": "Rua Cameron", "number": "66", "district": "Miguel Couto",
        "city": "Nova Iguaçu", "state": "RJ", "postalCode": "26070482",
        "latitude": -22.7089395, "longitude": -43.4347412
      },
      "contact": { "name": "Diogo", "phone": "+5521994977331", "instructions": "" }
    }
  }'
response 201
{
  "success": true,
  "data": {
    "delivery": { "id": "4e5f…", "object": "delivery", "status": "QUOTED",
                  "checkout_mode": "PRE_CHECKOUT", "payment_id": null },
    "quote": {
      "id": "7b2f…", "delivery_cost": 1500, "service_fee": 300,
      "total": 1800, "currency": "BRL", "expires_at": "2026-10-01T22:20:00.000Z"
    }
  },
  "error": null, "code": null, "message": null, "request_id": "…"
}

Guarde data.quote.id: ele é obrigatório no custeio. checkout_mode é PRE_CHECKOUT ou PAYMENT_FIRST (legado).

B) Custear — reserva o valor no dinheiro do pedido

request
curl -X POST https://vpnpay.com.br/api/public/v1/deliveries/4e5f…/funding \
  -H "Authorization: Bearer $VPNPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1043-custeio-1" \
  -d '{ "quote_id": "7b2f…", "payment_id": "9a8b…", "funding_source": "ONLINE_ORDER_PIX" }'

payment_id é obrigatório no pré-checkout (opcional no legado; se enviado, deve ser o pedido já vinculado). Numa única transação, a VPN Pay confere cotação válida, pagamento do mesmo tenant, da mesma unidade e com a mesma referência, fundos suficientes e ausência de custeio conflitante. O vínculo fica imutável e um pagamento custeia no máximo uma entrega ativa.

funding_sourceOrigem do dinheiroPré-requisitos
ONLINE_ORDER_PIXSaldo AVAILABLE gerado por aquele pedidoPedido pago e liquidado
ONLINE_ORDER_CARDPENDING daquele recebível de cartãoCaptura comprovada pelo provedor e teto de adiantamento habilitado para a unidade

Cartão: a captura confirmada autoriza contratar a entrega mesmo com o recebível ainda PENDING, respeitando o teto. Pré-autorização isolada não autoriza nada. Quando o adquirente liquida, a exposição é encerrada e só o líquido fica disponível — o frete já foi descontado uma única vez.

RecusaHTTPSignificado
QUOTE_EXPIRED409Cotação vencida — cote de novo
PAYMENT_REQUIRED422Pré-checkout sem payment_id
PAYMENT_MERCHANT_MISMATCH422Pagamento de outra unidade
PAYMENT_REFERENCE_MISMATCH422external_reference do pagamento diferente da entrega
DELIVERY_ALREADY_FUNDED409Entrega já custeada com outro pagamento
PAYMENT_ALREADY_BOUND409Pagamento já custeia outra entrega ativa
PAYMENT_NOT_CONFIRMED422Pedido ainda não está pago
CAPTURE_NOT_CONFIRMED422Pagamento sem lançamento contábil de captura
PROVIDER_CAPTURE_EVIDENCE_MISSING422Falta evidência de captura vinda do provedor
EXPOSURE_NOT_ENABLED402Teto de adiantamento no cartão não habilitado para a unidade
EXPOSURE_LIMIT_EXCEEDED402Valor acima do teto por entrega ou do teto total em aberto
INSUFFICIENT_ORDER_FUNDS402O próprio pedido não tem valor suficiente

C) Despachar — contrata a corrida

request
curl -X POST https://vpnpay.com.br/api/public/v1/deliveries/4e5f…/dispatch \
  -H "Authorization: Bearer $VPNPAY_API_KEY" \
  -H "Idempotency-Key: pedido-1042-despacho-1" \
  -H "Content-Type: application/json" -d '{}'

Resposta 202. Timeout ou resposta inconclusiva do parceiro mantêm a reserva, devolvem funding.dispatch = "TIMEOUT" e emitem o aviso delivery.dispatch_pending: nunca trate como falha nem repita com outra Idempotency-Key. A reserva só volta em falha definitiva, sem corrida criada e sem custo devido.

D) Cancelar

request
curl -X POST https://vpnpay.com.br/api/public/v1/deliveries/4e5f…/cancel \
  -H "Authorization: Bearer $VPNPAY_API_KEY" \
  -H "Idempotency-Key: pedido-1042-cancelamento-1" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "customer_canceled" }'

Sem custo do parceiro, a reserva volta integralmente (para AVAILABLE se o recebível já foi liquidado, senão para PENDING). Havendo taxa, a entrega fica com financial_adjustment: "PENDING_PARTNER_COST" e o ajuste é concluído no painel com a evidência da taxa. Taxa maior que o reservado é recusada (FEE_EXCEEDS_RESERVATION): nada é debitado em silêncio.

E) Estado financeiro da entrega

GET /deliveries/:id
{
  "id": "4e5f…", "object": "delivery",
  "merchant_id": "9d8c…", "payment_id": "8f0c…",
  "checkout_mode": "PRE_CHECKOUT",
  "external_reference": "pedido-1042",
  "status": "DISPATCHED", "message": null,
  "funding": {
    "source": "ONLINE_ORDER_CARD", "status": "RESERVED",
    "amount": 1800, "delivery_cost": 1500, "service_fee": 300,
    "refunded_amount": 0, "cancellation_fee": null,
    "dispatch": "DISPATCHED", "currency": "BRL"
  }
}

A obrigação com o parceiro nasce uma única vez, quando a corrida existe — não na liquidação do cartão. A fatura mensal do parceiro é importada, conferida e quitada com comprovante no painel da VPN Pay; não há API de escrita para isso. Avisos: delivery.quoted, delivery.authorized, delivery.dispatched, delivery.dispatch_pending, delivery.status_changed, delivery.canceled, delivery.failed.

12. Faturas da frota própria
Somente leitura. Fechamento do ciclo, emissão do complemento e repasse aos entregadores são operações do painel.
MétodoCaminhoScope
GET/fleet/invoicesfleet_invoices:read
GET/fleet/invoices/:id_ou_numerofleet_invoices:read
ParâmetroValores
limit1 a 100 (padrão 20)
starting_afterpagination.next_cursor da página anterior
statusOPEN, OVERDUE, IN_REVIEW, PAID, FUNDED, PAYING, SETTLED
merchant_iduuid da unidade (dentro do escopo da chave)
request
curl "https://vpnpay.com.br/api/public/v1/fleet/invoices?limit=20&status=OPEN" \
  -H "Authorization: Bearer $VPNPAY_API_KEY"
curl "https://vpnpay.com.br/api/public/v1/fleet/invoices/FAT-2026-00002" \
  -H "Authorization: Bearer $VPNPAY_API_KEY"

Paginação estável por cursor, ordem fixa period_end desc, id desc. O detalhe aceita o identificador do ciclo ou o número da fatura. Avisos: fleet_invoice.created, fleet_invoice.charge_available e fleet_invoice.paid.

13. Avisos automáticos (webhooks)
EventoQuando
payment.createdCobrança criada
payment.paidPagamento confirmado
payment.failedCobrança falhou
payment.settledRecebível liquidado; líquido disponível
payment.chargebackContestação de cartão aberta ou revertida
refund.createdDevolução criada
refund.completedDevolução concluída
refund.failedDevolução falhou
payout.createdRepasse criado
payout.completedRepasse concluído
payout.failedRepasse falhou
payout.blockedRepasse bloqueado por risco
recipient.updatedRecebedor atualizado
corpo enviado
{
  "id": "3c9a…",              // id do evento (use para deduplicar)
  "type": "payment.paid",
  "created_at": "2026-09-12T22:10:04.000Z",
  "delivery_id": "a71f…",     // id desta tentativa
  "data": {
    "id": "8f0c…",
    "object": "payment",
    "status": "PAID",
    "amount": 4990,
    "currency": "BRL",
    "external_reference": "pedido-1042",
    "merchant_id": "5f1f…",
    "recipient_id": null,
    "payment_intent_id": null,
    "created_at": "2026-09-12T22:00:00.000Z",
    "updated_at": "2026-09-12T22:10:03.000Z"
  }
}
cabeçalhos
X-VPNPay-Event: payment.paid
X-VPNPay-Delivery: a71f…
X-VPNPay-Timestamp: 1789245004
X-VPNPay-Signature: sha256=9b1d…

A assinatura é HMAC SHA-256 do texto timestamp + "." + corpo bruto, usando o segredo do endereço de aviso, em hexadecimal. Compare sempre com o corpo bruto, antes de qualquer parse.

PHP / Laravel
Route::post('/vpnpay/webhook', function (Request $request) {
    $raw       = $request->getContent();
    $timestamp = $request->header('X-VPNPay-Timestamp');
    $signature = $request->header('X-VPNPay-Signature'); // sha256=...

    $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $raw, config('services.vpnpay.webhook_secret'));
    if (! hash_equals($expected, (string) $signature)) {
        return response('invalid signature', 401);
    }
    if (abs(time() - (int) $timestamp) > 300) {
        return response('stale', 400);
    }

    $event = json_decode($raw, true);

    // at-least-once: ignore se já processou este id
    if (WebhookEvent::where('event_id', $event['id'])->exists()) {
        return response('ok', 200);
    }
    WebhookEvent::create(['event_id' => $event['id'], 'type' => $event['type']]);

    if ($event['type'] === 'payment.paid') {
        Order::where('reference', $event['data']['external_reference'])->update(['paid' => true]);
    }

    return response('ok', 200); // sempre 200 quando recebido
});
Node / TypeScript
import crypto from "node:crypto";
import express from "express";

const app = express();

app.post("/vpnpay/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  const raw = req.body.toString("utf8");
  const timestamp = String(req.header("X-VPNPay-Timestamp"));
  const signature = String(req.header("X-VPNPay-Signature"));

  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.VPNPAY_WEBHOOK_SECRET!)
    .update(`${timestamp}.${raw}`)
    .digest("hex");

  const ok = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!ok) return res.status(401).send("invalid signature");
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.status(400).send("stale");

  const event = JSON.parse(raw);
  if (await alreadyProcessed(event.id)) return res.status(200).send("ok");
  await markProcessed(event.id);

  if (event.type === "payment.paid") await markOrderPaid(event.data.external_reference);

  res.status(200).send("ok");
});
  • Entrega at-least-once: o mesmo evento pode chegar mais de uma vez. Deduplique pelo id do evento.
  • Responda 2xx rapidamente; processamento demorado deve ir para fila no seu lado.
  • Novas tentativas em 30s, 2min, 10min, 1h, 6h e 24h — no máximo 6 tentativas.
  • Só endereços https são aceitos.
14. Erros
HTTPcodeQuando acontece
400invalid_requestCampo ausente, tipo errado, JSON inválido, valor não inteiro em centavos
401unauthorizedChave ausente, inválida, revogada ou expirada
403forbiddenChave sem o scope exigido pelo endpoint
404not_foundRecurso inexistente ou de outro cliente (mesma resposta, por segurança)
409idempotency_conflictMesma Idempotency-Key com corpo diferente
409conflictConflito de estado do recurso
422unprocessableRegra de negócio recusou: saldo insuficiente, risco, capability indisponível, provedor recusou
429rate_limitedLimite de chamadas por minuto excedido
500internal_errorFalha inesperada da VPN Pay

Indisponibilidade de provedor chega como 422 unprocessable com a mensagem do motivo (a VPN Pay não devolve 503: a chamada foi recebida e avaliada). Todo erro traz request_id — informe-o no suporte.

409 idempotency_conflict
HTTP/1.1 409 Conflict
{
  "success": false,
  "data": null,
  "error": "idempotency_conflict",
  "code": "idempotency_conflict",
  "message": "Idempotency-Key já usada com outro conteúdo",
  "request_id": "…"
}
16. Limite de uso
Tipo de chamadaLimite padrão
Leitura (GET)240 por minuto, por chave
Escrita (POST/PATCH/DELETE)60 por minuto, por chave

Os limites são configuráveis por conta. Toda resposta traz os cabeçalhos:

cabeçalhos de limite
X-RateLimit-Limit: 240
X-RateLimit-Remaining: 236
X-RateLimit-Reset: 2026-09-12T22:11:00.000Z

Ao estourar, a resposta é 429 rate_limited: aguarde a janela virar e repita com a mesma Idempotency-Key.

17. Exemplos práticos

A) Criar Pix com Smart Routing

curl
curl -X POST https://vpnpay.com.br/api/public/v1/payments \
  -H "Authorization: Bearer $VPNPAY_API_KEY" \
  -H "Idempotency-Key: pedido-1042-pagamento-1" \
  -H "Content-Type: application/json" \
  -d '{"amount":4990,"external_reference":"pedido-1042","payer":{"name":"Maria Souza","document":"12345678909"}}'
PHP / Laravel
$res = Http::withToken(config('services.vpnpay.key'))
    ->withHeaders(['Idempotency-Key' => "pedido-{$order->id}-pagamento-1"])
    ->post('https://vpnpay.com.br/api/public/v1/payments', [
        'amount' => $order->total_cents,
        'external_reference' => "pedido-{$order->id}",
        'payer' => ['name' => $order->customer_name, 'document' => $order->customer_document],
    ])->throw()->json();

$order->update([
    'payment_id' => $res['data']['id'],
    'pix_copia_e_cola' => $res['data']['br_code'],
]);
Node / TypeScript
const res = await fetch("https://vpnpay.com.br/api/public/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VPNPAY_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `pedido-${order.id}-pagamento-1`,
  },
  body: JSON.stringify({
    amount: order.totalCents,
    external_reference: `pedido-${order.id}`,
    payer: { name: order.customerName, document: order.customerDocument },
  }),
});
const { data, message } = await res.json();
if (!res.ok) throw new Error(message);
console.log(data.br_code, data.qr_code);

B) Consultar um Pix

curl
curl https://vpnpay.com.br/api/public/v1/payments/8f0c… -H "Authorization: Bearer $VPNPAY_API_KEY"
Node / TypeScript
const r = await fetch(`https://vpnpay.com.br/api/public/v1/payments/${paymentId}`, {
  headers: { Authorization: `Bearer ${process.env.VPNPAY_API_KEY}` },
});
const { data } = await r.json();
if (data.status === "PAID") await releaseOrder(data.external_reference);

C) Devolução parcial

curl
curl -X POST https://vpnpay.com.br/api/public/v1/refunds \
  -H "Authorization: Bearer $VPNPAY_API_KEY" \
  -H "Idempotency-Key: pedido-1042-devolucao-1" \
  -H "Content-Type: application/json" \
  -d '{"payment_id":"8f0c…","amount":1500,"reason":"MERCHANT_OUT_OF_STOCK","liabilities":[{"party":"MERCHANT","amount":1500,"recipient_id":"b3c1…"}]}'
PHP / Laravel
Http::withToken(config('services.vpnpay.key'))
    ->withHeaders(['Idempotency-Key' => "pedido-{$order->id}-devolucao-1"])
    ->post('https://vpnpay.com.br/api/public/v1/refunds', [
        'payment_id' => $order->payment_id,
        'amount' => 1500,
        'reason' => 'MERCHANT_OUT_OF_STOCK',
        'liabilities' => [['party' => 'MERCHANT', 'amount' => 1500, 'recipient_id' => $store->recipient_id]],
    ])->throw();

D) Solicitar repasse

curl
curl -X POST https://vpnpay.com.br/api/public/v1/payouts \
  -H "Authorization: Bearer $VPNPAY_API_KEY" \
  -H "Idempotency-Key: repasse-2026-09-12-loja-12" \
  -H "Content-Type: application/json" \
  -d '{"recipient_id":"b3c1…","pix_key_id":"77aa…","amount":25000}'
Node / TypeScript
const r = await fetch("https://vpnpay.com.br/api/public/v1/payouts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VPNPAY_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `repasse-${day}-${recipientId}`,
  },
  body: JSON.stringify({ recipient_id: recipientId, pix_key_id: pixKeyId, amount: cents }),
});
const { data, message } = await r.json();
if (!r.ok) throw new Error(message);
if (data.status === "BLOCKED") notifyRiskTeam(data.id);

E) Consultar saldo

curl
curl "https://vpnpay.com.br/api/public/v1/recipients/b3c1…/balance?currency=BRL" -H "Authorization: Bearer $VPNPAY_API_KEY"
curl "https://vpnpay.com.br/api/public/v1/balances" -H "Authorization: Bearer $VPNPAY_API_KEY"

F) Receber payment.paid

Node / TypeScript (resumo)
// 1. valide a assinatura (ver seção Avisos)
// 2. deduplique pelo event.id
// 3. só então marque o pedido como pago
if (event.type === "payment.paid") {
  await db.orders.update({
    where: { reference: event.data.external_reference },
    data: { status: "PAID", paidAt: event.created_at, amountCents: event.data.amount },
  });
}
return new Response("ok", { status: 200 });
18. Exemplo de integração de um delivery
Do pedido ao repasse, na ordem real.
  1. Pedido criado. Seu sistema fecha o carrinho e calcula o total em centavos.
  2. POST /payments com external_reference igual ao número do pedido e Idempotency-Key derivada dele. Sem provider_connection_id, o Smart Routing escolhe o provedor.
  3. Exiba o Pix ao cliente usando br_code (copia e cola) e qr_code. Mantenha o pedido como aguardando pagamento — nunca libere pelo simples fato de a cobrança ter sido criada.
  4. Receba payment.paid no seu endereço de aviso, valide a assinatura, deduplique pelo id do evento e marque o pedido como pago. Como contingência, consulte GET /payments/:id.
  5. Entrega. O valor líquido do pedido fica como saldo do recebedor (loja e/ou entregador), conforme as regras de taxas e split configuradas.
  6. Repasse. No ciclo combinado, consulte o saldo disponível e chame POST /payouts com a chave Pix ativa do recebedor. Trate BLOCKED como pendência de risco, não como falha.
  7. Devolução quando necessário. POST /refunds informando o pagamento, o valor e quem assume (loja, entregador, parceiro ou plataforma). Aguarde refund.completed.
19. OpenAPI e versão em texto

A especificação legível por máquina fica em https://vpnpay.com.br/api/public/v1/openapi.json (acesso público, sem chave). Ela inclui securitySchemes, scopes, esquemas de requisição e resposta, exemplos, erros, o cabeçalho de idempotência, os esquemas dos avisos e os enums públicos — pronta para importar no Postman, Insomnia ou gerar um SDK.

Esta mesma documentação também é publicada em texto puro (Markdown) em /docs.md, sem login e sem depender de JavaScript — útil para leitura por ferramentas de IA e por sistemas de integração.