VolgaPay — Integration guide for merchants
VolgaPay payments API: PIX, card, crypto, payment links, balance, withdrawals and webhooks.
- Base URL (current environment):
https://volgapay.com - Interactive documentation:
https://volgapay.com/docs - OpenAPI:
https://volgapay.com/openapi.yaml - Format: JSON, UTF-8
- Values: always in cents, integers.
R$ 10,00=1000. - Authentication: API key in header
Authorization: Bearer vp_...
VolgaPay does not have a separate sandbox. Tests are done in production with low value and real payer data.
1. Primeiros passos
- Create a merchant account on the VolgaPay dashboard.
- Activate the 2FA of the holder. Creating API keys requires 2FA.
- Create a API key in Settings → API Keys.
- Save the token
vp_...: he appears just once. - Register the Allowed IPs of your application (optional, but recommended).
- Register one webhook endpoint to receive
payment.succeeded,payment.failed, etc. - Consult
GET /v1/methodsto view your account methods, currencies, and fees.
Scopes
| Scope | For what |
|---|---|
payments:read | Check payments and list |
payments:write | Create, capture, cancel and refund |
payouts:read | Consult withdrawals |
payouts:write | Request withdrawals |
balance:read | Check balance |
kyc:read / kyc:write | Submit and query KYC |
webhooks:read / webhooks:write | Manage endpoints and deliveries |
admin | Administrative operations (do not use on the merchant server) |
Use the smallest scope possible. A production key should not be used in the browser or mobile applications.
2. Autenticação
Authorization: Bearer vp_<key_id>_<secret>
Content-Type: application/json
Accept: application/json
Example:
curl https://volgapay.com/v1/balance \
-H "Authorization: Bearer vp_SEU_TOKEN"
IP allowlist
Each API key can have a list of IPs/CIDRs. If the list is populated, requests from other IPs receive 401.
Rotation
Revoke the old key and create a new one. Revocation is immediate.
3. Idempotência
Send Idempotency-Key in every operation that creates money:
POST /v1/paymentsPOST /v1/payments/{id}/refundPOST /v1/payouts
Idempotency-Key: pedido-1001
Rules:
- The same key + the same body returns the original result.
- Same key + different body returns
409. - Use a new key per order; to repeat the same request after timeout, use the same key.
- Keep the key at your bank along with the order.
4. Criar pagamento PIX
POST /v1/payments
Body
| Field | Type | Mandatory | Description |
|---|---|---|---|
amount | whole | yes | Value in cents |
currency | string | sim | BRL for PIX |
method | string | sim | pix |
country | string | no | BR (inferred for PIX) |
description | string | não | Appears on your statement/dashboard |
customer | object | yes on PIX | Payer |
metadata | objeto | não | Your data, returned in the consultation |
capture | boolean | não | Card only; default true |
Payer (customer) on PIX
VolgaPay requires full payer in production:
| Campo | Obrigatório | Rule |
|---|---|---|
name | sim | Full name, minimum 2 characters |
document | sim | Valid CPF or CNPJ (with or without punctuation) |
phone | sim | Telephone with area code. E.g.: +5511999990000 |
email | recommended | Valid email |
external_id | não | Your customer identifier |
Without a valid name, document and telephone number, the charge will be refused with
422and codecobranca_recusada_pelo_provedor.
Example
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" }
}'
Answer 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_colais the PIX copy and paste.- Generate the QR code image from it (do not depend on
qr_codebe a URL). - The initial status is
requires_action. expires_atis the validity informed by the acquirer.feeenetare calculated by your fee schedule.
Status
| Status | Meaning |
|---|---|
requires_action | Waiting for the payer to pay the PIX |
processing | In processing |
succeeded | Paid and credited to net balance |
failed | Refused/failed |
canceled | Canceled |
expired | Expired without payment |
refunded | Returned |
partially_refunded | Partially returned |
chargeback | Dispute |
Release the order only with status = succeeded (and ideally confirming via GET /v1/payments/{id}).
5. Consultar pagamento
GET /v1/payments/{id}
curl https://volgapay.com/v1/payments/01M760P713WDTJ7RF0W6DDZP9D \
-H "Authorization: Bearer vp_SEU_TOKEN"
Returns full payment, including pix, fee, net, paid_at, failure e metadata.
List
GET /v1/payments?limit=20&before=<id>
Capture card
POST /v1/payments/{id}/capture com {"amount": 1000} (optional).
Cancel
POST /v1/payments/{id}/cancel
At PIX, cancellation and refund may not be available via the API. Use the VolgaPay dashboard for MED/returns. The cancellation endpoint may return an error to PIX.
Refund
POST /v1/payments/{id}/refund
{ "amount": 1000, "reason": "Pedido cancelado" }
Subject to method and provider.
6. Webhooks
Register endpoint
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"]
}'
Answer:
{
"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
secretappears uma única vez. - Store it in an environment variable, never in the front-end.
- Use HTTPS with a valid certificate.
- VolgaPay does not send webhook to
localhost, private IP or internal network.
Events
payment.succeededpayment.failedpayment.canceledpayment.expiredpayment.refunded(partial or full refund)payment.chargeback(MED/chargeback open, won or lost)payout.paidpayout.failed
Payload
{
"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"
}
}
The webhook payload is lean. Consult
GET /v1/payments/{payment_id}to getpix,fee,net,metadataepaid_at.
Subscription
Headers:
X-VolgaPay-Event-Id: 01M...
X-VolgaPay-Signature: t=1791824530,v1=5d2f...64 hex...
The signature is:
HMAC-SHA256(secret, "<t>.<corpo cru>")
- Use your body raw, without reserialize the JSON.
- Compare in constant time.
- Refuse
tmore than 5 minutes apart. - The signature covers only the body; don't rely on headers to decide the event.
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);
Node.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();
Retries and duplicates
- Reply
2xxin up to 15 seconds. - VolgaPay tries again in case of failure (up to 8 attempts).
- The same event can arrive more than once. Discard by
X-VolgaPay-Event-Id. - Always confirm payment on the API before crediting balance.
Check deliveries
GET /v1/webhook-deliveries
Shows status, attempts, HTTP code and error for the latest deliveries.
6.1 Disputes (MED) and chargebacks
VolgaPay receives notices from the acquirer and reflects the blocking and settlement in the merchant's balance automatically.
| Situation | What happens to the balance |
|---|---|
Open dispute/MED (contestacao.aberta) | The disputed amount comes out of the available balance and remains blocked in hold. It cannot be withdrawn or transferred. |
Dispute closed in favor of the store (refunded: false) | The blocked amount returns to the available balance. |
Dispute accepted in favor of the payer (refunded: true) | The blocked amount is debited; it will be returned to the payer through the acquirer's account. |
Open chargeback (chargeback.aberto) | The value is blocked, as in MED. |
Chargeback won (won) | The blocked amount returns to the available balance. |
Chargeback lost (lost) | The blocked amount is debited. |
Chargeback reversed (reversed) | The amount returns to the available balance. |
Refund (venda.devolvida) | The amount returned is debited from the available balance. If the return comes with a accepted MED, there is no double debit. |
If the merchant does not have enough balance, the opening continues and the available balance may become negative (debt). The locked value appears in On hold on the panel.
Consult disputes
GET /v1/chargebacks Lists account disputes. Each item brings kind (med or chargeback), amount, currency, status (pending, won, lost) and provider_reference.
Configure warnings
In the Vizzo account webhook, use the URL https://volgapay.com/v1/webhooks/provider/vizzo and mark events contestacao.aberta, contestacao.encerrada, chargeback.aberto, chargeback.encerrado e venda.devolvida. The signature X-Vizzo-Signature is automatically validated.
7. Saldo
GET /v1/balance?currency=BRL
{
"object": "balance",
"currency": "BRL",
"available": 970,
"payout_hold": 0
}
available is the balance available for withdrawal, in cents.
8. Saques (PIX-out)
Prerequisites:
- KYC approved.
- Sufficient available balance.
- Valid PIX key.
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"
}
Status:
pending_approval: awaiting admin approvalprocessing: sent to providerpaid: paidfailed: failedrejected: refused
Consulte GET /v1/payouts/{id}. The webhook payout.paid is also sent.
Withdrawals may require manual approval. The balance is held while the withdrawal is pending.
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" }
}
Then use customer_id em POST /v1/payments.
GET /v1/customers/{id} consultation.
10. Links de pagamento
POST /v1/payment-links
{
"amount": 10000,
"currency": "BRL",
"description": "Plano anual",
"methods": ["pix", "card", "volgapay"],
"max_installments": 12
}
The answer includes url e token. Share the url with the customer.
GET /v1/payment-linkslist.POST /v1/payment-links/{id}/deactivatedeactivates.- The link methods are validated against the merchant's active acquirers. Non-acquirer methods are declined at creation and checkout.
- If the merchant has several PIX routes (several tokens from the same acquirer), the checkout shows a single PIX option. The route used is the one defined by the merchant's risk group.
11. Métodos e taxas
GET /v1/methods
Returns your account's active methods, currencies, countries, fields, and rates. Use catalog e fees to set up your checkout.
12. Erros
Formato:
{
"error": {
"type": "unprocessable_entity",
"code": "unprocessable_entity",
"message": "Mensagem legível",
"details": {}
}
}
| HTTP | Significado |
|---|---|
400 | Invalid request |
401 | Missing/invalid API key or IP not allowed |
403 | No scope or access denied |
404 | Resource not found |
409 | Conflict/idempotence |
422 | Business rule (invalid payer, insufficient balance, etc.) |
429 | Rate limit |
502 | Provider refused/failed |
503 | Provider unavailable |
PIX provider errors may come with code:
provedor_indisponivel— account/provider not yet active; nothing was charged.fora_do_horario— account only generates charges at a certain time.cobranca_recusada_pelo_provedor— payer/amount details refused.cobranca_vencida— resending expired PIX; use another Idempotency-Key.
13. Boas práticas de segurança
- Never place the API key in the front-end, mobile app or repository.
- Use HTTPS and validate the certificate.
- Store the webhook secret in an environment variable.
- Always check the webhook signature.
- Always confirm payment in the API before releasing the order.
- Use
Idempotency-Keyand keep it in your bank. - Restrict the API key by IP.
- Activate 2FA on the holder.
- Rotate keys periodically.
- Do not use fictitious payer data in production.
14. Exemplo completo de PIX
- Your server creates the payment:
POST /v1/payments
Idempotency-Key: pedido-1001
- The answer brings
id,pix.copia_e_colaeexpires_at.
- Your checkout shows the QR/copy-and-paste.
- The customer pays.
- VolgaPay sends
payment.succeededto your webhook.
- Your server verifies the signature, queries
GET /v1/payments/{id}and confirmstatus = succeededand the value.
- Your server credits the order uma única vez.
- If the webhook does not arrive, polling
GET /v1/payments/{id}reconcile.
15. Extensibilidade — novas adquirentes
The API is acquirer agnostic. When VolgaPay adds a new PSP or a new internal route:
- the base URL does not change;
- the endpoints
/v1/...do not change; - your API key remains the same;
- webhooks continue with the same format and signature;
GET /v1/methodsnow reflects new methods/currencies/rates.
VolgaPay routes internally by method, currency, country and risk group. You don't need to create a new integration or issue new tokens to each acquirer.
16. Suporte
- Documentation:
https://volgapay.com/docs - OpenAPI:
https://volgapay.com/openapi.yaml - VolgaPay support: via the merchant panel (integration’s only support channel)
When opening support, inform:
- merchant id;
- payment id;
- UTC time;
- HTTP route and method;
- HTTP code and
codeof the error; Idempotency-Keyused.