💳 Paynow mBank Library

Nieoficjalna biblioteka Node.js/TypeScript do integracji z bramką płatniczą Paynow od mBanku.

🚀 Instalacja

npm install paynow-mbank-lib

📖 Szybki Start

1. Konfiguracja

import { PaynowClient } from 'paynow-mbank-lib';
// lub: const { PaynowClient } = require('paynow-mbank-lib');

const paynow = new PaynowClient({
  apiKey: 'twoj-api-key',
  signatureKey: 'twoj-signature-key',
  environment: 'sandbox' // lub 'production'
});

2. Tworzenie płatności

const payment = await paynow.createPayment({
  amount: 1000, // 10.00 PLN (w groszach)
  externalId: 'zamowienie-123',
  description: 'Zakup w sklepie online',
  buyer: {
    email: '[email protected]',
    firstName: 'Jan',
    lastName: 'Kowalski'
  },
  continueUrl: 'https://twojsklep.pl/success'
});

console.log('URL płatności:', payment.redirectUrl);
console.log('ID płatności:', payment.paymentId);

3. Sprawdzanie statusu płatności

const status = await paynow.getPaymentStatus(payment.paymentId);
console.log('Status:', status.status);
console.log('Kwota:', status.amount);

4. Obsługa powiadomień (webhooks)

// Express.js przykład
app.post('/paynow-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['signature'];
  const body = req.body.toString();

  // Weryfikacja podpisu
  if (!paynow.verifyNotification(signature, body)) {
    return res.status(400).send('Invalid signature');
  }

  // Parsowanie powiadomienia
  const notification = paynow.parseNotification(body);
  
  console.log(`Płatność ${notification.paymentId} ma status: ${notification.status}`);
  
  // Tutaj przetwarzaj zmianę statusu
  switch (notification.status) {
    case 'CONFIRMED':
      console.log('Płatność potwierdzona!');
      break;
    case 'REJECTED':
      console.log('Płatność odrzucona');
      break;
  }

  res.status(200).send('OK');
});

🔧 API Reference

PaynowClient

Konstruktor

new PaynowClient(config: PaynowConfig)

Metody

createPayment(request: PaymentRequest): Promise<PaymentResponse>

Tworzy nową płatność w systemie Paynow.

getPaymentStatus(paymentId: string): Promise<PaymentStatusResponse>

Pobiera aktualny status płatności.

verifyNotification(signature: string, data: string): boolean

Weryfikuje podpis powiadomienia webhook od Paynow. Używa prostego HMAC-SHA256 dla body.

parseNotification(data: string): PaymentNotification

Parsuje dane powiadomienia od Paynow do typowanej struktury.

Typy danych

export interface PaynowConfig {
  apiKey: string;
  signatureKey: string;
  environment?: 'sandbox' | 'production';
}

export interface PaymentBuyer {
  email: string;
  firstName?: string;
  lastName?: string;
  phone?: {
    prefix: string; // e.g., "+48"
    number: string; // e.g., "123456789"
  };
  address?: {
    billing?: {
      street?: string;
      houseNumber?: string;
      apartmentNumber?: string;
      zipcode?: string;
      city?: string;
      county?: string;
      country?: string; // e.g., "PL"
    };
    shipping?: {
      street?: string;
      houseNumber?: string;
      apartmentNumber?: string;
      zipcode?: string;
      city?: string;
      county?: string;
      country?: string; // e.g., "PL"
    };
  };
  locale?: string; // e.g., "pl", "en" default is "pl-PL"
  externalId?: string | number; // optional buyer ID
}

export interface OrderItem {
  name: string;
  producer?: string;
  category: string;
  quantity: number;
  price: number; // cena w groszach
}

export interface PaymentRequest {
  amount: number; // w groszach (np. 1000 = 10.00 PLN)
  externalId: string | number;
  description: string;
  buyer: PaymentBuyer;
  continueUrl?: string; // URL powrotu z płatności
  currency?: 'PLN' | 'EUR' | 'USD' | 'GBP'; // domyślnie 'PLN'
  validityTime?: number; // ważność płatności w sekundach
  orderItems?: OrderItem[];
}

export enum PaymentStatus {
  NEW = 'NEW',
  PENDING = 'PENDING',
  CONFIRMED = 'CONFIRMED',
  REJECTED = 'REJECTED',
  ERROR = 'ERROR',
  EXPIRED = 'EXPIRED',
  ABANDONED = 'ABANDONED',
}

🔐 Bezpieczeństwo i Podpisy

Biblioteka automatycznie obsługuje podpisywanie żądań zgodnie z wymaganiami Paynow:

API Requests (createPayment)

• Używa złożonego schematu z posortowanymi headers, parameters i body
• Tworzy strukturę payload: { headers: {...}, parameters: {...}, body: "..." }
• Oblicza HMAC-SHA256 i koduje jako Base64

Webhook Notifications (verifyNotification)

• Używa prostszego schematu: bezpośredni HMAC-SHA256 z surowego body
• Weryfikuje podpis z nagłówka Signature

// Przykład manualnej weryfikacji (nie trzeba - robiąc automatycznie):
const crypto = require('crypto');
const hmac = crypto.createHmac('sha256', signatureKey);
hmac.update(webhookBody, 'utf8');
const calculatedSignature = hmac.digest('base64');

🧪 Testowanie

# Uruchom wszystkie testy
npm test

# Testy w trybie watch
npm run test:watch

# Testy z pokryciem kodu
npm test -- --coverage

🏗️ Rozwój

# Sklonuj repozytorium
git clone https://github.com/antistv/paynow-mbank-lib.git

# Zainstaluj zależności
npm install

# Budowanie w trybie watch
npm run build:watch

# Linting
npm run lint
npm run lint:fix

⚠️ Uwagi

• To jest nieoficjalna biblioteka, nie jest związana z mBankiem
• Zawsze testuj integrację w środowisku sandbox przed wdrożeniem
• Pamiętaj o zabezpieczeniu kluczy API

🤝 Contributing

1. Fork projektu
2. Stwórz branch na feature (git checkout -b feature/AmazingFeature)
3. Commit zmiany (git commit -m 'Add some AmazingFeature')
4. Push do brancha (git push origin feature/AmazingFeature)
5. Otwórz Pull Request

📄 Licencja

MIT License - zobacz LICENSE po szczegóły.

🔗 Linki

• Oficjalna dokumentacja Paynow
• Paynow Sandbox
• Issues
• NPM Package