@plyaz/payments

The Unified Payment Engine for the Plyaz Ecosystem.

The @plyaz/payments SDK is a full-stack, enterprise-grade payment processing architecture designed to handle all of your monetary needs—from simple credit card charges to complex blockchain transactions. It provides a unified, type-safe interface for your NestJS backend and Next.js/React frontend, ensuring a secure, scalable, and seamless payment experience.

✨ Why Plyaz Payments?

• Unified Provider Interface: A single API to rule them all. Integrate once and connect to various providers like Stripe, PayPal, MoonPay, and future Web3 protocols with minimal code changes.
• Built-in Security & Compliance: Engineered with PCI compliance at its core. We handle the sensitive data so you don't have to, with features like webhook signature verification and robust fraud detection.
• Intelligent Routing: Maximize success rates and minimize costs. Our smart routing engine automatically selects the best payment provider for each transaction based on performance, cost, and regional rules.
• Full-Stack Event-Driven Architecture: All transactions, from initiation to completion, are tracked by a comprehensive, event-driven system. Get real-time updates and build responsive user experiences and audit trails effortlessly.
• Type-Safe from End to End: Leveraging TypeScript across the entire stack, from NestJS DTOs to React component props, to eliminate bugs and ensure a consistent data flow.

📦 Installation

Get started in seconds with your preferred package manager:

Bash

Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML pnpm add @plyaz/payments

🚀 Quick Start

Backend: NestJS Payments Module

Easily integrate the payments module into your NestJS application. The module manages provider adapters, webhooks, and core payment services.

TypeScript

Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML // src/app.module.ts import { Module } from '@nestjs/common'; import { PaymentsModule } from '@plyaz/payments/backend'; @Module({ imports: [ PaymentsModule.forRoot({ // Your payments configuration providers: [ { provider: 'stripe', enabled: true, credentials: { apiKey: process.env.STRIPE_SECRET_KEY, publishableKey: process.env.STRIPE_PUBLISHABLE_KEY, }, // ... more config }, ], // ... other feature flags and settings }), ], }) export class AppModule {}

Frontend: React Custom Hook

Use our custom usePayment hook to orchestrate the entire payment flow in your React components.

TypeScript

Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML // components/Checkout.tsx 'use client'; import React from 'react'; import { usePayment } from '@plyaz/payments/frontend'; import { PaymentForm } from '@plyaz/payments/frontend/components'; function CheckoutPage() { const { processPayment, loading, error, result } = usePayment(); const handlePayment = async (formData) => { try { const paymentResult = await processPayment({ amount: { amount: 1000, currency: 'USD' }, paymentMethod: formData.method, // ... }); // Handle success, e.g., show a confirmation message console.log('Payment completed:', paymentResult); } catch (err) { // The hook handles errors and sets the 'error' state console.error('Payment failed:', err); } }; if (result) { return Payment successful! Transaction ID: {result.transactionId} ; } return ( {error && Error: {error.message} } ); }

⚙️ Architecture

The payments SDK is built on a distributed, package-based architecture to ensure separation of concerns and maximum testability.

Key Architectural Layers

• @plyaz/payments (This Package): The core payments logic. Contains NestJS services, React hooks, and provider adapters.
• @plyaz/types: Defines all shared types, interfaces, and enums, ensuring consistency from API requests to database entities.
• @plyaz/errors: Handles all payment-specific exceptions, providing standardized error codes for consistent feedback and monitoring.
• @plyaz/events: The heart of our event-driven system. It emits a wide range of payment lifecycle events (e.g., payment.completed, refund.processing, chargeback.received).
• @plyaz/config: Centralizes all provider credentials, feature flags, and intelligent routing rules.

🛡️ Security by Design

We've built a multi-layered security framework into the core of @plyaz/payments.

• Webhook Verification: All incoming webhooks from payment providers are automatically validated with HMAC signatures to prevent spoofing and ensure data integrity.
• Rate Limiting: NestJS guards protect your payment endpoints from abuse and brute-force attacks.
• Typed Error Handling: The @plyaz/errors integration ensures that security-related failures (e.g., fraud flags, velocity checks) are properly categorized and logged.

🤝 Contributing

We welcome contributions to expand our provider adapters, add new payment methods, or improve our core architecture. Please refer to our CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the ISC License.