@veruspay/react

Drop-in PIX checkout component for React apps. The simplest way to accept PIX payments in Brazil.

Installation

npm install @veruspay/react

Peer dependencies: React 18+

Quick start

import { PixCheckout } from '@veruspay/react'

export default function CheckoutPage() {
  return (
    <PixCheckout
      clientId="cli_xxxxxxxx"
      clientSecret="your-client-secret"
      accountId="uuid-da-conta"
      pixKey="uuid-chave-evp"
      amount={4990}              // R$ 49,90 (em centavos)
      description="Pedido #123"
      onSuccess={(txId) => console.log('Pago!', txId)}
    />
  )
}

That's it. The component handles QR Code generation, copy-paste, and payment polling automatically.

Sandbox (testing)

Add sandbox to enable test mode — no real payments are processed. A "Simulate payment" button appears so you can confirm the payment without scanning the QR Code.

<PixCheckout
  clientId="cli_xxxxxxxx"
  clientSecret="your-client-secret"
  accountId="uuid-da-conta"
  pixKey="uuid-chave-evp"
  amount={4990}
  description="Pedido #123"
  sandbox
  onSuccess={(txId) => alert('Pagamento simulado: ' + txId)}
/>

In sandbox mode the SDK automatically points to https://dev-api-bank.veruspay.co.

Props

<PixCheckout>

| Prop | Type | Required | Default | Description | |---|---|---|---|---| | clientId | string | ✅ | — | Client ID from VerusPay dashboard | | clientSecret | string | ✅ | — | Client secret from VerusPay dashboard | | accountId | string | ✅ | — | Your VerusPay account UUID | | pixKey | string | ✅ | — | EVP PIX key UUID registered to the account | | amount | number | ✅ | — | Amount in cents (e.g. 4990 = R$ 49,90) | | description | string | ✅ | — | Payment description | | type | 'static' \| 'dynamic' | — | 'static' | QR Code type | | name | string | — | 'VerusPay' | Recipient name (static QR only) | | city | string | — | 'Brasil' | Recipient city (static QR only) | | expirationSeconds | number | — | 3600 | Expiration in seconds (dynamic QR only) | | sandbox | boolean | — | false | Enable sandbox/test mode | | apiUrl | string | — | auto | Custom API base URL (overrides sandbox flag) | | title | string | — | 'Pagar com PIX' | Title shown above the amount | | className | string | — | — | CSS class for the container | | style | CSSProperties | — | — | Inline styles for the container | | onSuccess | (txId: string) => void | — | — | Called when payment is confirmed | | onError | (error: Error) => void | — | — | Called on error |

Components & hooks

<PixQrCode>

Renders just the QR Code image, without the full checkout UI.

import { PixQrCode } from '@veruspay/react'

<PixQrCode emv={qrCodeEmv} size={200} />

| Prop | Type | Default | Description | |---|---|---|---| | emv | string | — | PIX EMV payload string | | size | number | 200 | Width and height in pixels |

usePixPayment

Hook for building a fully custom checkout UI.

import { usePixPayment } from '@veruspay/react'

function CustomCheckout() {
  const { qrCodeEmv, status, error, copyCode, copied, simulatePayment } = usePixPayment({
    clientId: 'cli_xxxxxxxx',
    clientSecret: 'your-client-secret',
    accountId: 'uuid-da-conta',
    pixKey: 'uuid-chave-evp',
    amount: 4990,
    description: 'Pedido #123',
    sandbox: true,
    onSuccess: (txId) => console.log('Pago!', txId),
  })

  if (status === 'loading') return <p>Gerando QR Code…</p>
  if (status === 'error') return <p>Erro: {error}</p>
  if (status === 'completed') return <p>✅ Pagamento confirmado!</p>

  return (
    <div>
      <img src={/* render qrCodeEmv */} />
      <button onClick={copyCode}>{copied ? 'Copiado!' : 'Copiar código'}</button>
      <button onClick={simulatePayment}>Simular pagamento</button>
    </div>
  )
}

VerusPayClient

Low-level API client for advanced use cases (Node.js, custom integrations).

import { VerusPayClient, SANDBOX_API_URL } from '@veruspay/react'

const client = new VerusPayClient(SANDBOX_API_URL)
const token = await client.getToken('cli_xxxxxxxx', 'your-client-secret')

const qr = await client.createDynamicQrCode(token, {
  accountId: 'uuid-da-conta',
  pixKey: 'uuid-chave-evp',
  amount: 4990,
  description: 'Pedido #123',
  expirationSeconds: 3600,
})

console.log(qr.txId, qr.qrCodeEmv)

Getting credentials

1. Sign up at veruspay.co
2. Go to Homologação (Sandbox) to get test credentials
3. Use sandbox prop for testing — switch to production credentials when ready

License

MIT