VPN Pay — Documentação da API
Pública e somente leitura. Operações e dados continuam exigindo chave autenticada.
| Item | Valor |
|---|---|
| Endereço base | https://vpnpay.com.br/api/public/v1 |
| Ambientes | Um endereço por conta. A chave define se é chave de produção (vpnp_live_) ou de teste (vpnp_test_). |
| Formato | JSON em todas as chamadas e respostas (application/json; charset=utf-8). |
| Valores | Sempre inteiros em centavos. R$ 12,34 = 1234. Nunca envie decimais. |
| Moeda | Campo currency com 3 letras (padrão BRL). |
| Identificação da chamada | Toda resposta traz request_id. Guarde-o para suporte. |
| Versão | A 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:
{
"success": true,
"data": { "id": "…", "object": "payment" },
"error": null,
"code": null,
"message": null,
"request_id": "0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"
}{
"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"
}Authorization: Bearer vpnp_live_9f2a1c4d7b.5c1e…segredo
Content-Type: application/jsonA 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:write | Consultar / criar cobranças Pix |
| payouts:read / payouts:write | Consultar / solicitar repasses |
| refunds:read / refunds:write | Consultar / criar devoluções |
| recipients:read / recipients:write | Consultar / cadastrar recebedores |
| balances:read | Consultar saldos |
| reconciliation:read | Consultar conciliação |
| webhooks:manage | Gerenciar avisos automáticos |
| Situação | HTTP | code |
|---|---|---|
| Cabeçalho ausente, chave inválida, revogada ou expirada | 401 | unauthorized |
| Chave válida, mas sem o scope exigido pelo endpoint | 403 | forbidden |
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.
| Método | Caminho | Scope |
|---|---|---|
| POST | /payments | payments:write |
| GET | /payments | payments:read |
| GET | /payments/:id | payments:read |
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| amount | inteiro (centavos) | sim | Valor da cobrança, maior que zero |
| currency | string(3) | não | Padrão BRL |
| payer.name | string | sim | Nome de quem paga |
| payer.document | string | sim | CPF ou CNPJ de quem paga |
| payer.email | string | não | E-mail do pagador |
| merchant_id | uuid | não | Unidade comercial da VPN Pay |
| recipient_id | uuid | não | Recebedor do valor líquido; quando ausente, usa o recebedor principal da unidade |
| external_reference | string | não | Seu identificador do pedido |
| metadata | objeto | não | Dados livres do seu sistema (devolvidos na consulta) |
| provider_connection_id | uuid | não | Conexão específica do provedor |
| expires_in_minutes | inteiro >= 5 | não | Validade 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.
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" }
}'{
"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).
| status | Significado |
|---|---|
| CREATED | Cobrança registrada, ainda sem Pix emitido |
| PENDING | Pix emitido, aguardando pagamento |
| PROCESSING | Provedor processando a confirmação |
| PAID | Pago e confirmado — só aqui libere o pedido |
| FAILED | Falha confirmada pelo provedor |
| CANCELED | Cancelada antes do pagamento |
| EXPIRED | Prazo do Pix vencido sem pagamento |
| UNKNOWN | Resposta sem confirmação; nunca trate como pago nem recrie a cobrança |
| RECONCILIATION_REQUIRED | Divergência detectada; em conferência pela VPN Pay |
| Método | Caminho | Scope |
|---|---|---|
| POST | /payouts | payouts:write |
| GET | /payouts | payouts:read |
| GET | /payouts/:id | payouts:read |
| Campo | Tipo | Obrigatório |
|---|---|---|
| recipient_id | uuid | sim |
| pix_key_id | uuid (chave Pix ativa do recebedor) | sim |
| amount | inteiro (centavos) | sim |
| currency | string(3) | não (BRL) |
| merchant_id | uuid | não |
| provider_connection_id | uuid | nã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.
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 }'| Método | Caminho | Scope |
|---|---|---|
| POST | /refunds | refunds:write |
| GET | /refunds | refunds:read |
| GET | /refunds/:id | refunds:read |
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| payment_id | uuid | sim | Pagamento pago que será devolvido |
| amount | inteiro (centavos) | sim | Igual ao pagamento = total; menor = parcial |
| reason | enum | sim | CUSTOMER_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[] | lista | sim | Quem assume o valor. A soma precisa ser igual a amount |
| liabilities[].party | enum | sim | MERCHANT, DRIVER, PARTNER, OTHER ou PLATFORM |
| liabilities[].amount | inteiro | sim | Parcela assumida |
| liabilities[].recipient_id | uuid | condicional | Obrigatório quando party não é PLATFORM |
| notes | string | não | Observaçã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_REQUIREDpara conferência manual. - Estados: CREATED, PENDING, PROCESSING, DONE, FAILED, CANCELED, UNKNOWN, RECONCILIATION_REQUIRED.
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…" } ]
}'| Método | Caminho | Scope |
|---|---|---|
| POST | /recipients | recipients:write |
| GET | /recipients | recipients:read |
| GET | /recipients/:id | recipients:read |
| GET | /recipients/:id/balance | balances:read |
| Campo | Tipo | Obrigatório | Validação |
|---|---|---|---|
| type | enum | sim | MERCHANT, DRIVER, PARTNER ou OTHER |
| legal_name | string | sim | Nome/razão social |
| display_name | string | não | Nome de exibição |
| document_type | string | não | CPF ou CNPJ |
| document_number | string | não | Validado com dígito verificador; não pode repetir no mesmo cliente |
| string | não | Formato de e-mail válido | |
| phone | string | não | DDD + número |
| external_reference | string | não | Seu 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.
| Método | Caminho | Retorno |
|---|---|---|
| GET | /balances | Saldos do cliente por conta e moeda |
| GET | /recipients/:id/balance?currency=BRL | Saldo disponível do recebedor (em centavos) |
| Tipo | Significado |
|---|---|
| AVAILABLE | Disponível para repasse agora |
| PENDING | Confirmado, aguardando liberação |
| BLOCKED | Retido por risco, disputa ou decisão operacional |
| RECEIVABLE | Valor a receber, ainda não liquidado — não é sacável |
Importante: só AVAILABLE pode virar repasse. RECEIVABLE é expectativa de recebimento e nunca é sacável.
| Método | Caminho | Scope |
|---|---|---|
| GET | /reconciliation | reconciliation:read |
| GET | /reconciliation/:id | reconciliation: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.
| Método | Caminho | Scope |
|---|---|---|
| GET | /deliveries?limit=20 | delivery:read |
| GET | /deliveries/:id | delivery:read |
| POST | /deliveries/quotes | delivery:write |
| POST | /deliveries/:id/funding | delivery:write |
| POST | /deliveries/:id/dispatch | delivery:write |
| POST | /deliveries/:id/cancel | delivery: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.
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:
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": "" }
}
}'{
"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
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_source | Origem do dinheiro | Pré-requisitos |
|---|---|---|
| ONLINE_ORDER_PIX | Saldo AVAILABLE gerado por aquele pedido | Pedido pago e liquidado |
| ONLINE_ORDER_CARD | PENDING daquele recebível de cartão | Captura 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.
| Recusa | HTTP | Significado |
|---|---|---|
| QUOTE_EXPIRED | 409 | Cotação vencida — cote de novo |
| PAYMENT_REQUIRED | 422 | Pré-checkout sem payment_id |
| PAYMENT_MERCHANT_MISMATCH | 422 | Pagamento de outra unidade |
| PAYMENT_REFERENCE_MISMATCH | 422 | external_reference do pagamento diferente da entrega |
| DELIVERY_ALREADY_FUNDED | 409 | Entrega já custeada com outro pagamento |
| PAYMENT_ALREADY_BOUND | 409 | Pagamento já custeia outra entrega ativa |
| PAYMENT_NOT_CONFIRMED | 422 | Pedido ainda não está pago |
| CAPTURE_NOT_CONFIRMED | 422 | Pagamento sem lançamento contábil de captura |
| PROVIDER_CAPTURE_EVIDENCE_MISSING | 422 | Falta evidência de captura vinda do provedor |
| EXPOSURE_NOT_ENABLED | 402 | Teto de adiantamento no cartão não habilitado para a unidade |
| EXPOSURE_LIMIT_EXCEEDED | 402 | Valor acima do teto por entrega ou do teto total em aberto |
| INSUFFICIENT_ORDER_FUNDS | 402 | O próprio pedido não tem valor suficiente |
C) Despachar — contrata a corrida
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
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
{
"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.
| Método | Caminho | Scope |
|---|---|---|
| GET | /fleet/invoices | fleet_invoices:read |
| GET | /fleet/invoices/:id_ou_numero | fleet_invoices:read |
| Parâmetro | Valores |
|---|---|
| limit | 1 a 100 (padrão 20) |
| starting_after | pagination.next_cursor da página anterior |
| status | OPEN, OVERDUE, IN_REVIEW, PAID, FUNDED, PAYING, SETTLED |
| merchant_id | uuid da unidade (dentro do escopo da chave) |
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.
| Evento | Quando |
|---|---|
| payment.created | Cobrança criada |
| payment.paid | Pagamento confirmado |
| payment.failed | Cobrança falhou |
| payment.settled | Recebível liquidado; líquido disponível |
| payment.chargeback | Contestação de cartão aberta ou revertida |
| refund.created | Devolução criada |
| refund.completed | Devolução concluída |
| refund.failed | Devolução falhou |
| payout.created | Repasse criado |
| payout.completed | Repasse concluído |
| payout.failed | Repasse falhou |
| payout.blocked | Repasse bloqueado por risco |
| recipient.updated | Recebedor atualizado |
{
"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"
}
}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.
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
});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
iddo 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.
| HTTP | code | Quando acontece |
|---|---|---|
| 400 | invalid_request | Campo ausente, tipo errado, JSON inválido, valor não inteiro em centavos |
| 401 | unauthorized | Chave ausente, inválida, revogada ou expirada |
| 403 | forbidden | Chave sem o scope exigido pelo endpoint |
| 404 | not_found | Recurso inexistente ou de outro cliente (mesma resposta, por segurança) |
| 409 | idempotency_conflict | Mesma Idempotency-Key com corpo diferente |
| 409 | conflict | Conflito de estado do recurso |
| 422 | unprocessable | Regra de negócio recusou: saldo insuficiente, risco, capability indisponível, provedor recusou |
| 429 | rate_limited | Limite de chamadas por minuto excedido |
| 500 | internal_error | Falha 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.
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": "…"
}As listagens (GET /payments, /payouts, /refunds, /recipients, /reconciliation) devolvem um array em data, com os registros mais recentes primeiro, limitados ao lote padrão do cliente. Ainda não há paginação por cursor nem filtros por período: para acompanhar alterações em tempo real use os avisos automáticos e, para um registro específico, a consulta por id. O único parâmetro de consulta aceito hoje é currency em /recipients/:id/balance.
| Tipo de chamada | Limite 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:
X-RateLimit-Limit: 240
X-RateLimit-Remaining: 236
X-RateLimit-Reset: 2026-09-12T22:11:00.000ZAo estourar, a resposta é 429 rate_limited: aguarde a janela virar e repita com a mesma Idempotency-Key.
A) Criar Pix com Smart Routing
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"}}'$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'],
]);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 https://vpnpay.com.br/api/public/v1/payments/8f0c… -H "Authorization: Bearer $VPNPAY_API_KEY"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 -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…"}]}'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 -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}'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 "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
// 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 });- Pedido criado. Seu sistema fecha o carrinho e calcula o total em centavos.
- POST /payments com
external_referenceigual ao número do pedido eIdempotency-Keyderivada dele. Semprovider_connection_id, o Smart Routing escolhe o provedor. - Exiba o Pix ao cliente usando
br_code(copia e cola) eqr_code. Mantenha o pedido como aguardando pagamento — nunca libere pelo simples fato de a cobrança ter sido criada. - 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. - Entrega. O valor líquido do pedido fica como saldo do recebedor (loja e/ou entregador), conforme as regras de taxas e split configuradas.
- Repasse. No ciclo combinado, consulte o saldo disponível e chame
POST /payoutscom a chave Pix ativa do recebedor. TrateBLOCKEDcomo pendência de risco, não como falha. - Devolução quando necessário.
POST /refundsinformando o pagamento, o valor e quem assume (loja, entregador, parceiro ou plataforma). Aguarderefund.completed.
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.