Payra Node.js/TypeScript SDK

Oficjalna biblioteka kliencka Node.js / TypeScript dla bramki płatniczej Payra.pl. Pozwala na łatwą i szybką integrację płatności (w tym BLIK, szybkich przelewów oraz kart płatniczych) w Twojej aplikacji Node.js, Express, Next.js lub Discord Bocie.

Spis treści

• Instalacja
• Szybki Start
• Dokumentacja API
  • Inicjalizacja
  • Tworzenie płatności
  • Sprawdzanie statusu płatności
  • Dokonywanie zwrotu (Refund)
  • Weryfikacja podpisów Webhook
• Przykład użycia z Express.js (Webhook)
• Licencja

Instalacja

Zainstaluj pakiet w swoim projekcie przy użyciu wybranego menedżera pakietów:

npm install payra
# lub
yarn add payra
# lub
pnpm add payra

Szybki Start

Oto prosty przykład pokazujący, jak wygenerować link do płatności:

import { Payra } from 'payra';

const payra = new Payra('TWÓJ_KLUCZ_API');

async function createPayment() {
  try {
    const payment = await payra.transactions.create({
      amount: 19.99,
      currency: 'PLN',
      description: 'Zakup rangi VIP na serwerze',
      externalId: 'user123:vip_30d',
      email: '[email protected]',
      name: 'Jan Kowalski',
      redirectUrl: 'https://twojastrona.pl/powrot',
      callbackUrl: 'https://api.twojastrona.pl/webhook'
    });

    console.log('ID Transakcji:', payment.transactionId);
    console.log('Adres płatności (Checkout URL):', payment.checkoutUrl);
  } catch (error) {
    console.error('Wystąpił błąd:', error);
  }
}

createPayment();

Dokumentacja API

Inicjalizacja

Aby rozpocząć korzystanie z SDK, zaimportuj klasę Payra i utwórz jej instancję, przekazując swój Klucz API uzyskany w panelu Payra.pl.

import { Payra } from 'payra';

const payra = new Payra('TWÓJ_KLUCZ_API', {
  apiUrl: 'https://api.payra.pl/v1' // Opcjonalnie: własny adres API (domyślnie produkcyjny)
});

Tworzenie płatności

Służy do wygenerowania nowej sesji płatniczej. Zwraca obiekt z checkoutUrl, na który należy przekierować klienta.

const response = await payra.transactions.create({
  amount: number;             // Kwota płatności (np. 15.50)
  currency?: string;          // Domyślnie "PLN"
  description?: string;       // Opis transakcji
  externalId?: string;        // Twój własny identyfikator (np. "userId:itemId")
  callbackUrl?: string;       // Adres URL, na który zostanie wysłane powiadomienie Webhook
  redirectUrl?: string;       // Adres URL powrotny dla klienta po zakończeniu płatności
  channel?: 'BLIK' | 'P2P' | 'CARD' | 'TRANSFER'; // Ograniczenie metody płatności
  email?: string;             // E-mail klienta
  name?: string;              // Nazwa klienta
});

Sprawdzanie statusu płatności

Pobiera szczegółowe informacje o statusie danej transakcji.

const status = await payra.transactions.retrieve('TRANSACTION_ID');
console.log(status.status); // Zwraca: 'PENDING' | 'COMPLETED' | 'FAILED' | 'REFUNDED'

Dokonywanie zwrotu (Refund)

Umożliwia pełny lub częściowy zwrot środków dla transakcji o statusie COMPLETED.

const refundResult = await payra.transactions.refund('TRANSACTION_ID', 'Powód zwrotu (opcjonalnie)');

Weryfikacja podpisów Webhook

Metoda pozwalająca upewnić się, że powiadomienie o płatności wysłane na Twój serwer rzeczywiście pochodzi od Payra.pl i nie zostało zmodyfikowane.

const isValid = payra.transactions.verifySignature(
  {
    transactionId: req.body.transactionId,
    amount: req.body.amount.toString(),
    status: req.body.status
  },
  req.headers['payra-signature'] as string,
  'TWÓJ_WEBHOOK_SECRET' // Secret webhooka z panelu sprzedawcy
);

Przykład użycia z Express.js (Webhook)

Poniżej znajduje się kompletny przykład serwera obsługującego powiadomienia (Webhooki) o zmianie statusu płatności:

import express from 'express';
import { Payra } from 'payra';

const app = express();
app.use(express.json());

const payra = new Payra('TWÓJ_KLUCZ_API');
const WEBHOOK_SECRET = 'TWÓJ_WEBHOOK_SECRET'; // Pobierz z panelu Payra.pl

app.post('/webhook', (req, res) => {
  const { transactionId, amount, status, externalId } = req.body;
  const signature = req.headers['payra-signature'] as string;

  // 1. Weryfikacja autentyczności powiadomienia
  const isVerified = payra.transactions.verifySignature(
    { transactionId, amount: amount.toString(), status },
    signature,
    WEBHOOK_SECRET
  );

  if (!isVerified) {
    return res.status(403).json({ error: 'Błędny podpis webhooka' });
  }

  // 2. Obsługa statusu płatności
  if (status === 'COMPLETED') {
    console.log(`Płatność ${transactionId} zaangażowana pomyślnie na kwotę ${amount} PLN.`);
    console.log(`Dane zamówienia (externalId): ${externalId}`);
    
    // Nadaj rangę, aktywuj usługę lub zrealizuj zamówienie w bazie danych...
  } else if (status === 'FAILED') {
    console.log(`Płatność ${transactionId} została odrzucona lub anulowana.`);
  }

  // Odpowiedz serwerowi Payra statusem 200, aby potwierdzić odebranie
  res.status(200).json({ success: true });
});

app.listen(3000, () => console.log('Serwer nasłuchuje na porcie 3000'));

Licencja

Biblioteka jest udostępniana na warunkach licencji MIT.