HTML VolgaPay — Documentación para comerciantes
volgapagar /Documentos
APIv1 PIX • Tarjeta • Cripto Webhooks firmados

VolgaPay: guía de integración para comerciantes

API de pagos VolgaPay: PIX, tarjeta, criptografía, enlaces de pago, saldo, retiros y webhooks.

VolgaPay no tiene una zona de pruebas separada. Las pruebas se realizan en producción con datos reales del pagador y de bajo valor.


1. Primeiros passos

  1. Cree una cuenta de comerciante en el panel de VolgaPay.
  2. Activar el 2FA del titular. La creación de claves API requiere 2FA.
  3. Crear un clave API en Configuración → Claves API.
  4. guardar la ficha vp_...: él aparece solo una vez.
  5. Registre el IP permitidas de su solicitud (opcional, pero recomendado).
  6. Registra uno punto final del webhook recibir payment.succeeded, payment.failed, etc.
  7. Consultar GET /v1/methods para ver los métodos, monedas y tarifas de su cuenta.

Alcances

Alcance¿Para qué?
payments:readConsultar pagos y lista
payments:writeCrear, capturar, cancelar y reembolsar
payouts:readConsultar retiros
payouts:writeSolicitar retiros
balance:readConsultar saldo
kyc:read / kyc:writeEnviar y consultar KYC
webhooks:read / webhooks:writeGestionar puntos finales y entregas
adminOperaciones administrativas (no utilizar en el servidor comercial)

Utilice el alcance más pequeño posible. No se debe utilizar una clave de producción en el navegador ni en las aplicaciones móviles.


2. Autenticação

Authorization: Bearer vp_<key_id>_<secret>
Content-Type: application/json
Accept: application/json

Ejemplo:

curl https://volgapay.com/v1/balance \
  -H "Authorization: Bearer vp_SEU_TOKEN"

lista de direcciones IP permitidas

Cada clave API puede tener una lista de IP/CIDR. Si la lista está completa, las solicitudes de otras IP reciben 401.

Rotación

Revocar la clave anterior y crear una nueva. La revocación es inmediata.


3. Idempotência

enviar Idempotency-Key en toda operación que genere dinero:

Idempotency-Key: pedido-1001

Reglas:


4. Criar pagamento PIX

POST /v1/payments

cuerpo

campoTipoObligatorioDescripción
amountenterosiValor en centavos
currencycuerdasimBRL para foto
methodstringsimpix
countrystringnoBR (inferido para PIX)
descriptionstringnãoAparece en su estado de cuenta/panel
customerobjetosi en fotoPagador
metadataobjetonãoTus datos, devueltos en la consulta
capturebooleanonãoSólo tarjeta; predeterminado true

Pagador (customer) en foto

VolgaPay requiere un pagador completo en producción:

CampoObrigatórioregla
namesimNombre completo, mínimo 2 caracteres
documentsimCPF o CNPJ válido (con o sin puntuación)
phonesimTeléfono con código de área. Por ejemplo: +5511999990000
emailrecomendadoCorreo electrónico válido
external_idnãoSu identificador de cliente

Sin nombre, documento y número de teléfono válidos, el cargo será rechazado con 422 y código cobranca_recusada_pelo_provedor.

Ejemplo

curl -X POST https://volgapay.com/v1/payments \
  -H "Authorization: Bearer vp_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1001" \
  -d '{
    "amount": 1000,
    "currency": "BRL",
    "method": "pix",
    "country": "BR",
    "description": "Pedido 1001",
    "customer": {
      "name": "Cliente Exemplo",
      "email": "cliente@exemplo.com",
      "phone": "+5511999990000",
      "document": "529.982.247-25"
    },
    "metadata": { "order_id": "1001" }
  }'

respuesta 201

{
  "id": "01M760P713WDTJ7RF0W6DDZP9D",
  "object": "payment",
  "amount": 1000,
  "fee": 30,
  "net": 970,
  "currency": "BRL",
  "method": "pix",
  "status": "requires_action",
  "provider_reference": "13",
  "description": "Pedido 1001",
  "pix": {
    "qr_code": "0002010102122664...6304D12B",
    "copia_e_cola": "0002010102122664...6304D12B",
    "expires_at": "2026-11-12T19:17:23Z"
  },
  "created_at": "2026-11-11T19:17:23Z"
}

Estado

StatusSignificado
requires_actionEsperando que el pagador pague el PIX
processingEn procesamiento
succeededPagado y acreditado al saldo neto
failedRechazado/fallido
canceledCancelado
expiredCaducado sin pago
refundedDevuelto
partially_refundedParcialmente devuelto
chargebackDisputa

Liberar el pedido solo con status = succeeded (e idealmente confirmando a través de GET /v1/payments/{id}).


5. Consultar pagamento

GET /v1/payments/{id}

curl https://volgapay.com/v1/payments/01M760P713WDTJ7RF0W6DDZP9D \
  -H "Authorization: Bearer vp_SEU_TOKEN"

Devuelve el pago completo, incluyendo pix, fee, net, paid_at, failure e metadata.

Lista

GET /v1/payments?limit=20&before=<id>

tarjeta de captura

POST /v1/payments/{id}/capture com {"amount": 1000} (opcional).

Cancelar

POST /v1/payments/{id}/cancel

En PIX, es posible que la cancelación y el reembolso no estén disponibles a través de la API. Utilice el panel de VolgaPay para MED/devoluciones. El punto final de cancelación puede devolver un error a PIX.

Reembolso

POST /v1/payments/{id}/refund

{ "amount": 1000, "reason": "Pedido cancelado" }

Sujeto al método y al proveedor.


6. Webhooks

Registrar punto final

POST /v1/webhook-endpoints

curl -X POST https://volgapay.com/v1/webhook-endpoints \
  -H "Authorization: Bearer vp_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-sistema.com/webhooks/volgapay",
    "events": ["payment.succeeded", "payment.failed", "payment.canceled", "payment.expired"]
  }'

Respuesta:

{
  "id": "01...",
  "object": "webhook_endpoint",
  "url": "https://seu-sistema.com/webhooks/volgapay",
  "events": ["payment.succeeded", "..."],
  "secret": "whsec_...",
  "_notice": "Guarde o secret agora; ele não será exibido novamente."
}

Eventos

Carga útil

{
  "id": "01M...",
  "type": "payment.succeeded",
  "created_at": "2026-11-11T19:25:14+00:00",
  "data": {
    "payment_id": "01M760P713WDTJ7RF0W6DDZP9D",
    "amount": 1000,
    "currency": "BRL",
    "method": "pix",
    "status": "succeeded"
  }
}

La carga útil del webhook es reducida. Consultar GET /v1/payments/{payment_id} conseguir pix, fee, net, metadata e paid_at.

Suscripción

Encabezados:

X-VolgaPay-Event-Id: 01M...
X-VolgaPay-Signature: t=1791824530,v1=5d2f...64 hex...

La firma es:

HMAC-SHA256(secret, "<t>.<corpo cru>")

PHP

$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_VOLGAPAY_SIGNATURE'] ?? '';
preg_match('/t=(\d+),v1=([0-9a-f]{64})/', $header, $m);
$expected = hash_hmac('sha256', $m[1] . '.' . $raw, getenv('VOLGAPAY_WEBHOOK_SECRET'));
if (! hash_equals($expected, $m[2])) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
if ($event['type'] === 'payment.succeeded') {
    // consulte GET /v1/payments/{$event['data']['payment_id']} antes de liberar
}
http_response_code(200);

Nodo.js

const crypto = require('crypto');
const raw = req.rawBody; // Buffer, corpo cru
const secret = process.env.VOLGAPAY_WEBHOOK_SECRET;
const [t, v1] = String(req.get('X-VolgaPay-Signature')).match(/t=(\d+),v1=([0-9a-f]{64})/).slice(1);
const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(raw).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) return res.status(401).end();
const event = JSON.parse(raw.toString('utf8'));
if (event.type === 'payment.succeeded') { /* confirmar na API */ }
res.status(200).end();

Reintentos y duplicados

Consultar entregas

GET /v1/webhook-deliveries

Muestra estado, intentos, código HTTP y error de las últimas entregas.


6.1 Disputas (MED) y contracargos

VolgaPay recibe notificaciones del adquirente y refleja automáticamente el bloqueo y la liquidación en el saldo del comerciante.

Situación¿Qué sucede con el saldo?
Disputa/MED abierta (contestacao.aberta)El monto en disputa sale del saldo disponible y permanece bloqueado en hold. No se puede retirar ni transferir.
Disputa cerrada a favor de la tienda (refunded: false)El monto bloqueado vuelve al saldo disponible.
Disputa aceptada a favor del pagador (refunded: true)Se carga el importe bloqueado; será devuelto al pagador a través de la cuenta del adquirente.
Contracargo abierto (chargeback.aberto)El valor está bloqueado, como en MED.
Contracargo ganado (won)El monto bloqueado vuelve al saldo disponible.
Contracargo perdido (lost)Se carga el importe bloqueado.
Contracargo revertido (reversed)El importe vuelve al saldo disponible.
Devolución (venda.devolvida)El importe devuelto se debita del saldo disponible. Si la devolución viene con un MED aceptado, no hay doble débito.

Si el comerciante no tiene saldo suficiente, la apertura continúa y el saldo disponible puede volverse negativo (deuda). El valor bloqueado aparece en En espera en el tablero.

Consultar disputas

GET /v1/chargebacks Lista las disputas de la cuenta. Cada artículo trae kind (med o chargeback), amount, currency, status (pending, won, lost) y provider_reference.

Configurar los avisos

En el webhook de la cuenta de Vizzo, utilice la URL https://volgapay.com/v1/webhooks/provider/vizzo y marca los eventos contestacao.aberta, contestacao.encerrada, chargeback.aberto, chargeback.encerrado e venda.devolvida. La firma X-Vizzo-Signature se valida automáticamente.


7. Saldo

GET /v1/balance?currency=BRL

{
  "object": "balance",
  "currency": "BRL",
  "available": 970,
  "payout_hold": 0
}

available es el saldo disponible para retiro, en centavos.


8. Saques (PIX-out)

Requisitos previos:

POST /v1/payouts

{
  "amount": 1000,
  "currency": "BRL",
  "payout_method": "pix",
  "pix_key_type": "cpf",
  "pix_key": "529.982.247-25",
  "reason": "Saque do merchant"
}

Resposta 201:

{
  "id": "01...",
  "object": "payout",
  "amount": 1000,
  "fee": 0,
  "currency": "BRL",
  "status": "pending_approval",
  "payout_method": "pix",
  "pix_key_type": "cpf",
  "pix_key_last4": "7-25",
  "requested_at": "2026-11-11T20:00:00Z"
}

Estado:

Consulte GET /v1/payouts/{id}. El webhook payout.paid También se envía.

Los retiros pueden requerir aprobación manual. El saldo se retiene mientras el retiro esté pendiente.


9. Clientes

POST /v1/customers

{
  "external_id": "cliente-123",
  "name": "Cliente Exemplo",
  "email": "cliente@exemplo.com",
  "phone": "+5511999990000",
  "document": "529.982.247-25",
  "country": "BR",
  "metadata": { "plan": "pro" }
}

Entonces usa customer_id em POST /v1/payments.

GET /v1/customers/{id} consulta.


POST /v1/payment-links

{
  "amount": 10000,
  "currency": "BRL",
  "description": "Plano anual",
  "methods": ["pix", "card", "volgapay"],
  "max_installments": 12
}

La respuesta incluye url e token. Comparte el url con el cliente.


11. Métodos e taxas

GET /v1/methods

Devuelve los métodos, monedas, países, campos y tarifas activos de su cuenta. uso catalog e fees para configurar su pago.


12. Erros

Formato:

{
  "error": {
    "type": "unprocessable_entity",
    "code": "unprocessable_entity",
    "message": "Mensagem legível",
    "details": {}
  }
}
HTTPSignificado
400Solicitud no válida
401Clave API faltante/no válida o IP no permitida
403No se ha denegado el alcance ni el acceso
404Recurso no encontrado
409Conflicto/idempotencia
422Regla comercial (pagador no válido, saldo insuficiente, etc.)
429Límite de tarifa
502Proveedor rechazado/fallido
503Proveedor no disponible

Los errores del proveedor de PIX pueden venir con code:


13. Boas práticas de segurança


14. Exemplo completo de PIX

  1. Su servidor crea el pago:
POST /v1/payments
Idempotency-Key: pedido-1001
  1. La respuesta trae id, pix.copia_e_cola e expires_at.
  1. Su pago muestra el QR/copiar y pegar.
  1. El cliente paga.
  1. VolgaPay envía payment.succeeded a su webhook.
  1. Su servidor verifica la firma, consultas GET /v1/payments/{id} y confirmar status = succeeded y el valor.
  1. Su servidor acredita el pedido uma única vez.
  1. Si el webhook no llega, el sondeo GET /v1/payments/{id} reconciliar.

15. Extensibilidade — novas adquirentes

La API es independiente del adquirente. Cuando VolgaPay agrega un nuevo PSP o una nueva ruta interna:

VolgaPay realiza rutas internas por método, moneda, país y grupo de riesgo. No es necesario crear una nueva integración ni emitir nuevos tokens para cada adquirente.

16. Suporte

Al abrir soporte, informar:

VolgaPay: documentación para comerciantes. Valores siempre en céntimos. Guarda tus llaves de forma segura.