@pagnow/sdk-node

Official Node.js client for the PagNow payments API.

npm install @pagnow/sdk-node
# or: pnpm add @pagnow/sdk-node · yarn add @pagnow/sdk-node

Prefer raw HTTP? The API is plain REST + JSON — implement directly in any language using the in-dashboard docs (Integração → Documentação) and the OpenAPI reference at https://v2.pagnow.com/docs/payments/reference.

Quickstart

import { PagNow } from '@pagnow/sdk-node';

// The apikey identifies your tenant — no tenantId needed.
// baseUrl defaults to https://v2.pagnow.com (the live API host).
const pagnow = new PagNow({ apiKey: process.env.PAGNOW_API_KEY! });

const charge = await pagnow.payments.create({
  amount: 15_000, // 150.00 BRL in cents
  currency: 'BRL',
  paymentMethods: ['PIX'],
  customer: {
    name: 'Maria Silva',
    document: '12345678901',
    email: '[email protected]',
  },
  idempotencyKey: `order-${orderId}`,
});

console.log(charge.id, charge.pixCopyPaste);

// Refund (full or partial) and cancel an in-flight charge:
await pagnow.payments.refund(charge.id, { idempotencyKey: `refund-${charge.id}` });
await pagnow.payments.cancel(charge.id);

Payouts (withdrawals)

Move money out of your wallet to a PIX key, bank account, or crypto address.

const payout = await pagnow.payouts.create({
  type: 'PIX',
  amount: 10_000, // 100.00 BRL in cents
  currency: 'BRL',
  pixKey: '[email protected]',
  pixKeyType: 'EMAIL',
});

await pagnow.payouts.retrieve(payout.id);
await pagnow.payouts.list({ status: 'PENDING' });

A payout starts as PENDING. Whether it dispatches immediately or waits for manual review is controlled per-account by PagNow (the "auto-payout" setting — ask your account manager to enable it). Track the outcome with the withdrawal.* webhook events or by polling retrieve().

You may hold multiple wallets per currency. Omit walletId and the payout debits the currency's default wallet (or any spendable wallet with balance); pass walletId to target a specific one.

Wallets

const wallets = await pagnow.wallets.list();
// → [{ id, currency, label, walletType, isDefault, balance, pendingBalance, ... }]

await pagnow.wallets.retrieve(wallets[0].id);

Balances are in the smallest currency unit (cents). Wallet creation is handled by PagNow (admin); the SDK is read-only here.

Webhook verification

import express from 'express';
import { PagNow } from '@pagnow/sdk-node';

const pagnow = new PagNow({ apiKey: '...' });

app.post(
  '/webhooks/pagnow',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    try {
      const event = pagnow.webhooks.parse(
        req.body,
        req.header('X-PagNow-Signature'),
        process.env.PAGNOW_WEBHOOK_SECRET!,
      );
      // handle event...
      res.status(200).end();
    } catch {
      res.status(401).end();
    }
  },
);

Errors

Every non-2xx response throws a typed error:

| HTTP | Class | Use | |---|---|---| | 400 / 422 | PagNowValidationError | inspect .fieldErrors to know which field failed | | 401 / 403 | PagNowAuthError | rotate the API key, check tenant scoping | | 409 | PagNowConflictError | idempotency key reused by another tenant | | 5xx | PagNowError | retried automatically (default 3 attempts, jittered backoff) | | network | PagNowNetworkError | timed out or DNS failure |

Defaults

• 30-second per-request timeout (timeoutMs)
• 3 retry attempts on 5xx and network errors with full-jitter exponential backoff
• 4xx never retried
• Pass a custom fetch for testing

Dev mode

const pagnow = new PagNow({
  apiKey: 'pnk_dev_bootstrap_replace_me_before_any_real_traffic',
  baseUrl: 'http://localhost:8000',
});

Test keys are prefixed pnk_test_ (issued from the dashboard → Chaves API, "chave de teste"); live keys are pnk_live_.

License

MIT