VolgaPay: guía de integración para comerciantes
API de pagos VolgaPay: PIX, tarjeta, criptografía, enlaces de pago, saldo, retiros y webhooks.
- URL base (entorno actual):
https://volgapay.com - Documentación interactiva:
https://volgapay.com/docs - API abierta:
https://volgapay.com/openapi.yaml - Formato: JSON, UTF-8
- Valores: siempre en centavos, números enteros.
R$ 10,00=1000. - Autenticación: Clave API en el encabezado
Authorization: Bearer vp_...
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
- Cree una cuenta de comerciante en el panel de VolgaPay.
- Activar el 2FA del titular. La creación de claves API requiere 2FA.
- Crear un clave API en Configuración → Claves API.
- guardar la ficha
vp_...: él aparece solo una vez. - Registre el IP permitidas de su solicitud (opcional, pero recomendado).
- Registra uno punto final del webhook recibir
payment.succeeded,payment.failed, etc. - Consultar
GET /v1/methodspara ver los métodos, monedas y tarifas de su cuenta.
Alcances
| Alcance | ¿Para qué? |
|---|---|
payments:read | Consultar pagos y lista |
payments:write | Crear, capturar, cancelar y reembolsar |
payouts:read | Consultar retiros |
payouts:write | Solicitar retiros |
balance:read | Consultar saldo |
kyc:read / kyc:write | Enviar y consultar KYC |
webhooks:read / webhooks:write | Gestionar puntos finales y entregas |
admin | Operaciones 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:
POST /v1/paymentsPOST /v1/payments/{id}/refundPOST /v1/payouts
Idempotency-Key: pedido-1001
Reglas:
- La misma clave + el mismo cuerpo devuelve el resultado original.
- Misma clave + retornos de cuerpo diferentes
409. - Utilice una nueva clave por pedido; repetir el lo mismo Solicitud después del tiempo de espera, use la misma clave.
- Guarde la clave en su banco junto con el pedido.
4. Criar pagamento PIX
POST /v1/payments
cuerpo
| campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
amount | entero | si | Valor en centavos |
currency | cuerda | sim | BRL para foto |
method | string | sim | pix |
country | string | no | BR (inferido para PIX) |
description | string | não | Aparece en su estado de cuenta/panel |
customer | objeto | si en foto | Pagador |
metadata | objeto | não | Tus datos, devueltos en la consulta |
capture | booleano | não | Sólo tarjeta; predeterminado true |
Pagador (customer) en foto
VolgaPay requiere un pagador completo en producción:
| Campo | Obrigatório | regla |
|---|---|---|
name | sim | Nombre completo, mínimo 2 caracteres |
document | sim | CPF o CNPJ válido (con o sin puntuación) |
phone | sim | Teléfono con código de área. Por ejemplo: +5511999990000 |
email | recomendado | Correo electrónico válido |
external_id | não | Su identificador de cliente |
Sin nombre, documento y número de teléfono válidos, el cargo será rechazado con
422y códigocobranca_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"
}
pix.copia_e_colaes el Copiar y pegar foto.- Genere la imagen del código QR a partir de él (no dependa de
qr_codeser una URL). - El estado inicial es
requires_action. expires_ates la validez informada por el adquirente.feeenetse calculan según su lista de tarifas.
Estado
| Status | Significado |
|---|---|
requires_action | Esperando que el pagador pague el PIX |
processing | En procesamiento |
succeeded | Pagado y acreditado al saldo neto |
failed | Rechazado/fallido |
canceled | Cancelado |
expired | Caducado sin pago |
refunded | Devuelto |
partially_refunded | Parcialmente devuelto |
chargeback | Disputa |
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."
}
- O
secretaparece uma única vez. - Guárdelo en una variable de entorno, nunca en el front-end.
- Utilice HTTPS con un certificado válido.
- VolgaPay no envía webhook a
localhost, IP privada o red interna.
Eventos
payment.succeededpayment.failedpayment.canceledpayment.expiredpayment.refunded(reembolso parcial o total)payment.chargeback(MED/contracargo abierto, ganado o perdido)payout.paidpayout.failed
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}conseguirpix,fee,net,metadataepaid_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>")
- Usa tu cuerpo crudo, sin volver a serializar el JSON.
- Comparar en tiempo constante.
- Rechazar
tcon más de 5 minutos de diferencia. - La firma cubre sólo el cuerpo; No confíes en los encabezados para decidir el evento.
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
- Responder
2xxen hasta 15 segundos. - VolgaPay vuelve a intentarlo en caso de fallo (hasta 8 intentos).
- El mismo evento puede llegar más de una vez. Descartar por
X-VolgaPay-Event-Id. - Confirme siempre el pago en la API antes de acreditar el saldo.
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:
- Aprobado por KYC.
- Saldo disponible suficiente.
- Clave PIX válida.
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:
pending_approval: pendiente de aprobación del administradorprocessing: enviado al proveedorpaid: pagadofailed: fallórejected: rechazado
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.
10. Links de pagamento
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.
GET /v1/payment-linkslista.POST /v1/payment-links/{id}/deactivatedesactiva.- Los métodos de enlace se validan con los adquirentes activos del comerciante. Los métodos para no adquirentes se rechazan durante la creación y el pago.
- Si el comerciante tiene varias rutas PIX (varios tokens del mismo adquirente), el pago muestra una sola opción de PIX. La ruta utilizada es la definida por el grupo de riesgo del comerciante.
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": {}
}
}
| HTTP | Significado |
|---|---|
400 | Solicitud no válida |
401 | Clave API faltante/no válida o IP no permitida |
403 | No se ha denegado el alcance ni el acceso |
404 | Recurso no encontrado |
409 | Conflicto/idempotencia |
422 | Regla comercial (pagador no válido, saldo insuficiente, etc.) |
429 | Límite de tarifa |
502 | Proveedor rechazado/fallido |
503 | Proveedor no disponible |
Los errores del proveedor de PIX pueden venir con code:
provedor_indisponivel— cuenta/proveedor aún no activo; no se cobró nada.fora_do_horario— la cuenta solo genera cargos en un momento determinado.cobranca_recusada_pelo_provedor— detalles del pagador/importe rechazados.cobranca_vencida— reenviar PIX caducado; utilice otra clave de idempotencia.
13. Boas práticas de segurança
- Nunca coloque la clave API en el front-end, la aplicación móvil o el repositorio.
- Utilice HTTPS y valide el certificado.
- Guarde el secreto del webhook en una variable de entorno.
- Verifique siempre la firma del webhook.
- Confirma siempre el pago en la API antes de liberar el pedido.
- uso
Idempotency-Keyy guárdalo en tu banco. - Restrinja la clave API por IP.
- Active 2FA en el titular.
- Gire las claves periódicamente.
- No utilice datos ficticios del pagador en producción.
14. Exemplo completo de PIX
- Su servidor crea el pago:
POST /v1/payments
Idempotency-Key: pedido-1001
- La respuesta trae
id,pix.copia_e_colaeexpires_at.
- Su pago muestra el QR/copiar y pegar.
- El cliente paga.
- VolgaPay envía
payment.succeededa su webhook.
- Su servidor verifica la firma, consultas
GET /v1/payments/{id}y confirmarstatus = succeededy el valor.
- Su servidor acredita el pedido uma única vez.
- 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:
- la URL base no cambia;
- los puntos finales
/v1/...no cambies; - su clave API sigue siendo la misma;
- los webhooks continúan con el mismo formato y firma;
GET /v1/methodsahora refleja nuevos métodos/monedas/tasas.
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
- Documentación:
https://volgapay.com/docs - OpenAPI:
https://volgapay.com/openapi.yaml - Soporte VolgaPay: a través del panel de comerciantes (el único canal de soporte de integración)
Al abrir soporte, informar:
- identificación del comerciante;
- identificación de pago;
- hora UTC;
- Ruta y método HTTP;
- código HTTP y
codedel error; Idempotency-Keyusado.