html VolgaPay — Documentation for merchants
VolgaPay /Docs
API v1 PIX • Card • Crypto Signed webhooks

VolgaPay — Integration guide for merchants

VolgaPay payments API: PIX, card, crypto, payment links, balance, withdrawals and webhooks.

VolgaPay does not have a separate sandbox. Tests are done in production with low value and real payer data.


1. Primeiros passos

  1. Create a merchant account on the VolgaPay dashboard.
  2. Activate the 2FA of the holder. Creating API keys requires 2FA.
  3. Create a API key in Settings → API Keys.
  4. Save the token vp_...: he appears just once.
  5. Register the Allowed IPs of your application (optional, but recommended).
  6. Register one webhook endpoint to receive payment.succeeded, payment.failed, etc.
  7. Consult GET /v1/methods to view your account methods, currencies, and fees.

Scopes

ScopeFor what
payments:readCheck payments and list
payments:writeCreate, capture, cancel and refund
payouts:readConsult withdrawals
payouts:writeRequest withdrawals
balance:readCheck balance
kyc:read / kyc:writeSubmit and query KYC
webhooks:read / webhooks:writeManage endpoints and deliveries
adminAdministrative 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:

Idempotency-Key: pedido-1001

Rules:


4. Criar pagamento PIX

POST /v1/payments

Body

FieldTypeMandatoryDescription
amountwholeyesValue in cents
currencystringsimBRL for PIX
methodstringsimpix
countrystringnoBR (inferred for PIX)
descriptionstringnãoAppears on your statement/dashboard
customerobjectyes on PIXPayer
metadataobjetonãoYour data, returned in the consultation
capturebooleannãoCard only; default true

Payer (customer) on PIX

VolgaPay requires full payer in production:

CampoObrigatórioRule
namesimFull name, minimum 2 characters
documentsimValid CPF or CNPJ (with or without punctuation)
phonesimTelephone with area code. E.g.: +5511999990000
emailrecommendedValid email
external_idnãoYour customer identifier

Without a valid name, document and telephone number, the charge will be refused with 422 and code cobranca_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"
}

Status

StatusMeaning
requires_actionWaiting for the payer to pay the PIX
processingIn processing
succeededPaid and credited to net balance
failedRefused/failed
canceledCanceled
expiredExpired without payment
refundedReturned
partially_refundedPartially returned
chargebackDispute

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."
}

Events

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 get pix, fee, net, metadata e paid_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>")

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

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.

SituationWhat 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:

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:

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.


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.


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": {}
  }
}
HTTPSignificado
400Invalid request
401Missing/invalid API key or IP not allowed
403No scope or access denied
404Resource not found
409Conflict/idempotence
422Business rule (invalid payer, insufficient balance, etc.)
429Rate limit
502Provider refused/failed
503Provider unavailable

PIX provider errors may come with code:


13. Boas práticas de segurança


14. Exemplo completo de PIX

  1. Your server creates the payment:
POST /v1/payments
Idempotency-Key: pedido-1001
  1. The answer brings id, pix.copia_e_cola e expires_at.
  1. Your checkout shows the QR/copy-and-paste.
  1. The customer pays.
  1. VolgaPay sends payment.succeeded to your webhook.
  1. Your server verifies the signature, queries GET /v1/payments/{id} and confirm status = succeeded and the value.
  1. Your server credits the order uma única vez.
  1. 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:

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

When opening support, inform:

VolgaPay — documentation for merchants. Values ​​always in cents. Store your keys safely.