Prospay NestJS SDK

This package is a NestJS-based SDK for integrating with Prospay services, including:

• Customer onboarding
• Order transactions
• Invoice generation

It is designed to be reused across multiple projects so that you configure it once and use typed NestJS services instead of manually wiring HTTP calls every time.

Prerequisites

• Node.js: v18 or later (recommended)
• Package manager: npm (comes with Node), or yarn / pnpm
• NestJS: Your project should be a NestJS application (v11 recommended to match this SDK).

Installation

Once this SDK is published to your private registry or npm, install it in your Nest app:

npm install prospay-sdk

Quick start

Register the SDK module in your root AppModule (or any feature module):

import { Module } from '@nestjs/common';
import { ProspaySdkModule } from 'prospay-sdk';

@Module({
  imports: [
    ProspaySdkModule.register({
      productId: 'YOUR_PRODUCT_ID',
      productApiKey: 'YOUR_PRODUCT_API_KEY',
      baseUrl: 'https://sandbox.prospay.tech', // or your prod URL, e.g. https://prospay.tech
    }),
  ],
})
export class AppModule {}

Available services and methods

All services are registered in the module and can be injected anywhere in your Nest app.

Service manual

Below is a concise map of each service, its methods, and the underlying Prospay endpoints.

Auth (ProspayAuthService)

• authenticate() → POST /auth/api/v1.0/authenz/token?action=verify
  Headers auto-built: timestamp, resourceId (productId), keyhash (bcrypt of timestamp.productId.productApiKey). Returns auth payload (use its token in Authorization for other calls).

Customers (ProspayCustomerService)

• createCustomer(authToken, payload) → POST /customer/api/v3.0/customers
• updateCustomer(authToken, customerId, payload) → PATCH /customer/api/v3.0/customers/{customerId}/
• updateCustomerStatus(authToken, customerId, { productId, status }) → PATCH /customer/api/v3.0/customers/{customerId}/
• getCustomerById(authToken, customerId) → GET /customer/api/v3.0/customers/{customerId}?filter=all
• searchCustomers(authToken, params) → GET /customer/api/v3.0/customers/search?filter=...&mobileNumber=...&productCustomerId=...&customerType=...

Transactions (ProspayTransactionService)

• createTransaction(authToken, payload) → POST /uts/api/transactions
• addChargesToTransaction(authToken, transactionId, payload) → POST /uts/api/transactions/{transactionId}/charges
• searchTransactions(authToken, payload) → POST /uts/api/transactions/search
• getChargeSummary(authToken, { startDate, endDate }) → GET /uts/api/transactions/charge-summary/?startDate=...&endDate=...

Invoices (ProspayInvoiceService)

• generateInvoice(authToken, payload, callbackUrl?, proforma?) → POST /invoices/api/v2.0/generateInvoice
• generateBulkInvoice(authToken, payload, callbackUrl?) → POST /invoices/api/v2.0/generateBulkInvoice
  • Single-range payload: top-level fields (startDate, endDate, etc.).
  • Multi-invoice payload: pass a data array (same endpoint).
• getInvoiceStatus(authToken, refId) → GET /invoices/api/v2.0/invoice-status/{refId}

Example snippets

Authenticate and create a customer:

const authRes = await this.auth.authenticate();
const token = authRes?.token ?? authRes?.accessToken ?? authRes?.jwt;

await this.customers.createCustomer(token, {
  productId: 'SMEINFUL',
  productCustomerId: 'MGC2',
  orgName: 'Mega city',
  customerType: 'cp',
  contacts: { email: '[email protected]', mobileNumber: '9110334567' },
});

Create a transaction:

await this.tx.createTransaction(token, {
  customerId: 'SMEINFUL000000000679668',
  entityType: 'order',
  referenceId: 'REF17735672330',
  currency: 'INR',
  vertical: 'customer',
  charges: [
    {
      head: 'OTHER HANDLING CHARGES - ECOM (FOV & FSC)',
      amount: 10050,
      hsnOrSac: '998314',
      isBillable: true,
      absorbedBy: 'customer',
      transactionType: 'credit',
      breakup: [
        { head: 'CGST', amount: 5025, appliedOn: ['base_amount'], tags: ['tax', 'gst'] },
        { head: 'SGST', amount: 5025, appliedOn: ['base_amount'], tags: ['tax', 'gst'] },
      ],
      metadata: [
        { key: 'tax_rate', value: '18%' },
        { key: 'calculation_method', value: 'percentage' },
      ],
    },
  ],
});

Generate an invoice and check status:

const gen = await this.invoice.generateInvoice(token, {
  templateName: 'IF_Invoice',
  productId: 'SMEINFUL',
  startDate: '2025-11-01',
  endDate: '2025-11-30',
  buyer_customerId: 'SMEINFUL000000000679668',
  seller_customerId: 'SMEINFUL000000000679668',
  due_date: '2025-12-15',
  invoice_no: 'PERFORMA-SF-8922-1',
  invoice_date: '12-12-2025',
  invoice_period: '01-November-2025 TO 30-November-2025',
}, 'https://your-callback.example');

const status = await this.invoice.getInvoiceStatus(token, gen.refId);

Error handling

• All HTTP errors throw (Axios behavior). In your app, try/catch and inspect err.response.status and err.response.data.
• Some APIs return structured errors (e.g., transactions conflict, customer exists). The SDK types capture common success shapes; errors are surfaced as thrown responses so you can branch by status/message.

Configuration notes

• productId and productApiKey are required; baseUrl is configurable (set to sandbox or prod).
• If you omit baseUrl, the SDK defaults to https://sandbox.prospay.tech.
• Timestamp and bcrypt hash for auth are handled internally; you only need to supply the product credentials.