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)
  • Zarządzanie subskrypcjami
• Weryfikacja podpisów Webhook
• Przykład użycia z Express.js (Webhook)
• Changelog
• 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)');

Zarządzanie subskrypcjami

Umożliwia programowe tworzenie, pobieranie oraz anulowanie cyklicznych subskrypcji klientów.

Tworzenie subskrypcji

Pozwala handlowcom zarejestrować i uruchomić nową cykliczną subskrypcję klienta po zatwierdzeniu karty.

const subscription = await payra.subscriptions.create({
  email: '[email protected]',                // E-mail płatnika
  planName: 'Dostęp Premium (Miesięczny)',  // Nazwa planu subskrypcyjnego
  amount: 29.99,                          // Kwota obciążenia cyklicznego
  currency: 'PLN',                        // Waluta (domyślnie PLN)
  callbackUrl: 'https://api.sklep.pl/sub-webhook', // Webhook do powiadomień o zmianach stanu
  cardBrand: 'Visa',                      // Nazwa marki karty (opcjonalnie)
  cardLast4: '4242',                      // Ostatnie 4 cyfry karty (opcjonalnie)
  nextBillingDate: '2026-09-04'           // Data kolejnej płatności (opcjonalnie)
});

Pobieranie szczegółów subskrypcji

Służy do odpytania systemu o status konkretnej subskrypcji po jej identyfikatorze.

const details = await payra.subscriptions.retrieve('SUBSCRIPTION_ID');
console.log(details.status); // Zwraca: 'ACTIVE' | 'PAUSED' | 'CANCELLED' | 'EXPIRED'

Anulowanie subskrypcji

Pozwala sprzedawcy anulować subskrypcję klienta bezpośrednio z poziomu zaplecza sklepu.

const result = await payra.subscriptions.cancel('SUBSCRIPTION_ID');

Generowanie adresu URL Portalu Klienta

Metoda pomocnicza do wygenerowania bezpiecznego, spersonalizowanego linku przekierowującego klienta do Portalu Klienta PayRa, gdzie może on samodzielnie zmienić kartę lub anulować subskrypcję:

const portalUrl = payra.subscriptions.getCustomerPortalUrl('[email protected]');
// Zwraca: https://portal.payra.pl?email=klient%40email.pl

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'));

Symulacja Środowiska Testowego (Sandbox API)

Wszystkie operacje sandboxowe korzystają z dedykowanej przestrzeni nazw /v1/sandbox na serwerze API. Pozwalają one deweloperom na pełne przetestowanie integracji webhooków płatności oraz odnowień cyklicznych bez konieczności angażowania rzeczywistych transakcji:

1. Symulowanie sukcesu płatności:

   • Endpoint: POST /v1/sandbox/payments/:id/simulate-success
   • Opis: Przełącza status transakcji oczekującej na COMPLETED i wysyła podpisany webhook payment.success na adres URL callbacku.

2. Symulowanie błędu płatności:

   • Endpoint: POST /v1/sandbox/payments/:id/simulate-fail
   • Opis: Przełącza status transakcji oczekującej na FAILED i wysyła podpisany webhook payment.failed.

3. Symulowanie cyklicznego rozliczenia subskrypcji:

   • Endpoint: POST /v1/sandbox/subscriptions/:id/simulate-billing
   • Opis: Tworzy nową powiązaną transakcję COMPLETED, przesuwa termin następnego okresu rozliczeniowego o 1 miesiąc oraz wysyła podpisany webhook subscription.billed.

Changelog

[1.2.0] - 2026-08-04

• Wdrożono dedykowane Sandbox API (/v1/sandbox) do symulacji transakcji i subskrypcji dla deweloperów.
• Zaimplementowano moduł zarządzania wieloma kartami płatniczymi (Multi-card) w bazie danych oraz Portalu Klienta.
• Dodano automatyczne powiadomienia e-mail o nadchodzących płatnościach wysyłane na 3 dni przed obciążeniem karty.

[1.1.0] - 2026-08-04

• Dodano moduł payra.subscriptions umożliwiający handlowcom tworzenie, pobieranie oraz anulowanie subskrypcji.
• Dodano metodę pomocniczą getCustomerPortalUrl(email) do generowania linków logowania do portalu klienta.
• Wdrożono typowanie TypeScript dla subskrypcji (CreateSubscriptionPayload oraz SubscriptionResponse).

[1.0.1] - 2026-08-04

• Wprowadzono nową, zaawansowaną klasę błędów PayraError z obsługą statusów i szczegółów odpowiedzi z serwera.
• Dodano wbudowany limit czasu żądania (timeout 10s) przez integrację z AbortController.
• Usprawniono walidację odpowiedzi serwera na wypadek błędów HTML/Cloudflare (np. Bad Gateway 502).

[1.0.0] - 2026-06-02

• Pierwsza oficjalna wersja SDK Payra z pełną obsługą tworzenia płatności jednorazowych, sprawdzania statusów transakcji, wykonywania refundacji oraz weryfikacji sygnatur webhooków.

Licencja

Biblioteka jest udostępniana na warunkach licencji MIT.