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, customerId, { startDate, endDate }) → GET /uts/api/transactions/charge-summary/{customerId}
• updateMetadata(authToken, transactionId, { metadata }) → PATCH /uts/api/transactions/{transactionId}/metadata
• cancelTransaction(authToken, transactionId, { chargeIds?, reason }) → POST /uts/api/transactions/{transactionId}/cancel
• markTransactionsReady(authToken, customerId, payload) → POST /uts/api/transactions/{customerId}/mark-ready
• unmarkTransactionsReady(authToken, customerId, payload) → POST /uts/api/transactions/{customerId}/unmark-ready

Invoices (ProspayInvoiceService)

• generateInvoice(authToken, payload, callbackUrl?, proforma?, einvoice?) → POST /invoices/api/generateInvoice
• generateBulkInvoice(authToken, payload, callbackUrl?, proforma?, einvoice?) → POST /invoices/api/generateBulkInvoice
• getInvoiceStatus(authToken, refId) → GET /invoices/api/invoice-status/{refId}
• getDynamicInvoices(authToken, query) → GET /invoices/api/dynamicInvoices
• generateEInvoice(authToken, payload, callbackUrl) → POST /invoices/api/e-invoice
• cancelEInvoice(authToken, invoiceNo, cancelReason, callbackUrl) → DELETE /invoices/api/e-invoice/cancel
• getEInvoiceStatus(authToken, refId) → GET /invoices/api/e-invoice/status/{refId}
• listInvoiceSeriesTokens(authToken) → GET /invoices/api/invoice-series-pattern/tokens
• createInvoiceSeriesPattern(authToken, payload) → POST /invoices/api/invoice-series-pattern
• listInvoiceSeriesPatterns(authToken) → GET /invoices/api/invoice-series-pattern
• linkTemplateToSeriesPattern(authToken, payload) → PUT /invoices/api/invoice-series-pattern/link-template
• resetInvoiceSeriesCounter(authToken, payload) → POST /invoices/api/invoice-series/reset-counter
• generateInvoiceFromProforma(authToken, payload, callbackUrl, einvoice?) → POST /invoices/api/generateInvoiceFromProforma

Ledger (ProspayLedgerService)

• getCustomerSummary(authToken, params) → GET /uts/api/ledgers/customers/{customerId}/summary
• getCustomerLedger(authToken, params) → GET /uts/api/ledgers/customers/{customerId}/ledger
• getHeadSummary(authToken, query) → GET /uts/api/ledgers/reports/heads
• getDateRangeSummary(authToken, params) → GET /uts/api/ledgers/customers/{customerId}/reports/date-range
• getTaxSummary(authToken, query) → GET /uts/api/ledgers/reports/tax
• getProfitLossSummary(authToken, query) → GET /uts/api/ledgers/reports/profit-loss

Wallet (ProspayWalletService)

• updateCreditLimit(authToken, walletId, payload) → PUT /uts/api/wallets/{walletId}/credit-limit
• changeWalletStatus(authToken, walletId, payload) → PUT /uts/api/wallets/{walletId}/status
• getWalletBalance(authToken, walletId) → GET /uts/api/wallets/{walletId}/balance
• getCustomerWallets(authToken, customerId) → GET /uts/api/wallets/customer/{customerId}
• searchWallets(authToken, payload) → POST /uts/api/wallets/search
• getWalletHistory(authToken, walletId, params) → GET /uts/api/wallets/{walletId}/history
• getDailySnapshot(authToken, walletId, snapshotDate) → GET /uts/api/wallets/{walletId}/snapshots
• getCustomerSnapshots(authToken, customerId, snapshotDate) → GET /uts/api/wallets/customer/{customerId}/snapshots
• addParticipant(authToken, walletId, payload) → POST /uts/api/wallets/{walletId}/participants
• removeParticipant(authToken, walletId, customerId, payload) → DELETE /uts/api/wallets/{walletId}/participants/{customerId}
• getParticipants(authToken, walletId, params) → GET /uts/api/wallets/{walletId}/participants

Organizations (ProspayOrganizationService)

• verifyKyc(authToken, id, payload) → PUT /wallet/api/v1.0/{id}/kyc
  • id: internal Tenant/organisation UUID.
  • payload (VerifyKycDto): one of
    • { gst }
    • { businesspan } or { signatorypan }
    • { aadhar }
    • { otp } (for Aadhaar OTP verification)
  • Response: { data, status } (KYC provider response)
• createOrganization(authToken, payload) → POST /wallet/api/v1.0/organisations
  • payload (CreateOrganizationDto): { groupId?, name, industryType, businessType, gstRegistered, orgcode?, cin?, tan? }.
  • Response: { status: 201, data: { tenantId, id } }
• updateOrganization(id, payload) → PUT /wallet/api/v1.0/organisations/{id}
  • payload (UpdateOrganizationDto) patches Tenant fields.
  • Response: { status: 200, data: { message, id } }
• getAllOrganizations(authToken, headers) → GET /wallet/api/v1.0/organisations
  • headers: { orgid?, tenantid? } plus Authorization.
  • Behaviour depends on role in JWT (TenantAdmin, SuperAdmin, OrgAdmin, ProductOwner).
  • Response: { data: TenantWithAddress[] }
• updateBankDetails(authToken, id, payload) → PUT /wallet/api/v1.0/{id}/bankDetails
  • payload (UpdateBankDetailsDto): { bankname, accountholdername, accountno, ifsccode }.
  • Response: { message: 'bankDetails updated successfully', status: 201 }
• changeStatus(authToken, id, { action }) → POST /wallet/api/v1.0/{id}?action=enable|disable
  • Only honoured for SuperAdmin in the service.
  • Response: { message: 'Status <action>', status: 200 }
• getOrganization(orgId) → GET /wallet/api/v1.0/{orgId}/organisation
  • Response: { message: 'Success', data: TenantWithAddress | null }
• updateKycStatus(orgId, { action }, payload) → POST /wallet/api/v1.0/kycstatus/{orgId}?action=approve|disapprove|pending|completed
  • payload (KycStatusDto): optional { message } for disapproval.
  • Sends email notifications from the service.
  • Response: { message: 'Status <action>', status: 200 }
• updatePaymentGatewayCut(authToken, orgId, payload) → PUT /wallet/api/v1.0/{orgId}/updatePaymentGatewayCut
  • payload (UpdatePaymentGatewayCutDto): { cut, orgFees? }.
  • Response: { message: 'payment gateway cut updated successfully' }

Products (ProspayProductService)

• createProduct(authToken, payload) → POST /product/api/v2.0/products/
  • payload is CreateProductDto (tenant + org + product master details).
  • Response: { data: ProductModel }
• deleteProduct(authToken, id) → DELETE /product/api/v2.0/products/{id}
  • id is the internal product UUID.
  • Response: { message: 'product removed successfully' }
• findProductByRole(authToken, headers) → GET /product/api/v2.0/products/byRole
  • headers: { orgid, tenantid, resourceid? } on top of Authorization.
  • Response: { data: ProductWithBranchOrgs[] }
• findAllProductsForOrg(authToken, headers) → GET /product/api/v2.0/products/
  • headers: { orgid, tenantid }.
  • Response: { data: ProductWithBranchOrgs[] } (cached per org in the service)
• findAllProductsForTenant(authToken, headers) → GET /product/api/v2.0/products/dependentProducts
  • headers: { orgid, tenantid }.
  • Response: { data: ProductWithBranchOrgs[] }
• findProduct(id) → GET /product/api/v2.0/products/{id}/findProduct
  • id is the internal product UUID.
  • Response: { data: ProductWithBranchOrgs | null }
• updateProductThreshold(authToken, id, { threshold }) → PUT /product/api/v2.0/products/{id}/updateThreshold
  • Response: { message: 'Product threshold updated successfully' }
• fetchBranchOrgDetails(authToken, id) → GET /product/api/v2.0/products/{id}/fetchBranchOrgDetails
  • id is a branchOrgId.
  • Response: { data: BranchOrgModel | null, status: 200 }
• findProductByCustomName(productid) → GET /product/api/v2.0/products/{productid}/findProductByCustomName
  • productid is the external product code (e.g. WP...).
  • Response: { data: ProductModel | null }
• fetchBranchOrgIdFromBranchCode(query) → GET /product/api/v2.0/products/branchorgs
  • query: { stateCode?, productid? }.
  • Response: { data: { branchOrgDetails?, ProductDetails? }, status: 200 }
• fetchBranchOrgDetail(id) → GET /product/api/v2.0/products/{id}/fetchBranchOrgDetail
  • id is a branchOrgId.
  • Response: { data: BranchOrgModel | null, status: 200 }
• findBranchByStateCode(authToken, stateCode) → GET /product/api/v2.0/products/findBranchByState/{stateCode}
  • Uses req.user.resourceId to resolve the product, then stateCode.
  • Response: { data: BranchOrgModel | null, status: 200 }
• updateProductBranchOrgs(authToken, productid, payload) → PUT /product/api/v2.0/products/{productid}/branchOrgs
  • productid is the external product code (e.g. WP...).
  • payload includes branchOrg[] with address + bank details.
  • Response: { message: 'Product updated successfully', createdBranchOrgs?, errors? }
• fetchBranchOrg(authToken, id, branchOrgId) → GET /product/api/v2.0/products/{id}/branchorgs/{branchOrgId}
  • Currently implemented same as fetchBranchOrgDetail in the service.
  • Response: { data: BranchOrgModel | null, status: 200 }
• updateBranchOrg(authToken, id, branchOrgId, payload) → PATCH /product/api/v2.0/products/{id}/branchorgs/{branchOrgId}
  • payload is { branchOrg: [ ...single branch payload... ] }.
  • Response: { message: 'branch org updated successfully', status: 200 }
• listBranchOrgs(authToken, productid) → GET /product/api/v2.0/products/listBranchOrgs/{productid}
  • productid is the external product code.
  • Response: { data: BranchOrgModel[], status: 200 }
• fetchBranchOrgByHoId(authToken, id) → GET /product/api/v2.0/products/fetchBranchOrgByHoId/{id}
  • id is a mapped HO id.
  • Response: { data: { orgName, gst, address, bankDetails, ... }, status: 200 }

Payment (ProspayPaymentService)

• generateQr(authToken, payload) → POST /payments/api/v2.0/QR
• generatePaymentLink(authToken, payload) → POST /payments/api/v2.0/paymentLink
• refundPayment(authToken, productOrderId, payload) → POST /payments/api/v2.0/payment/{productOrderId}/refund
• getPaymentStatus(authToken, productOrderId) → GET /payments/api/v2.0/payment/{productOrderId}/status

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',
  startDate: '2025-11-01',
  endDate: '2025-11-30',
  buyer_customerId: 'SMEINFUL000000000679668',
  seller_customerId: 'SMEINFUL000000000679668',
  invoiceNo: 'PERFORMA-SF-8922-1'
}, 'https://your-callback.example', false, false);

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

// Search dynamic invoices
const search = await this.invoice.getDynamicInvoices(token, {
  templateName: 'IF_Invoice',
  is_proforma: true,
  page_no: 1,
  page_limit: 10
});

// Generate E-invoice
const einv = await this.invoice.generateEInvoice(token, {
  invoiceNo: 'INV-123',
  billFrom: { /* ... */ },
  billTo: { /* ... */ },
  charges: [ /* ... */ ],
  invoiceAmount: 1180
}, 'https://your-callback.example');

// Convert proforma to invoice
const convert = await this.invoice.generateInvoiceFromProforma(token, {
  proformaData: [{ proformaInvoiceNumber: 'PERFORMA-SF-8922-1', customInvoiceNumber: 'INV-2025-001' }]
}, 'https://your-callback.example', true);

Advanced Transaction Search

The searchTransactions method now supports deep filtering:

await this.tx.searchTransactions(token, {
  page: 1,
  limit: 20,
  transactionFilters: {
    customerIds: ['CUST1'],
    entityTypes: ['order'],
    transactionDateRange: { start: '2024-01-01', end: '2024-01-31' }
  },
  chargeFilters: {
    heads: ['GST', 'PLATFORM_FEE'],
    isBillable: true
  },
  sorting: { sortBy: 'transactionDate', sortOrder: 'DESC' },
  includeOptions: { includeCharges: true, includeChargeBreakups: true }
});

New Management Methods

• Metadata: updateMetadata(token, txId, { metadata: [{ key: 'tag', value: 'val' }] })
• Cancellation: cancelTransaction(token, txId, { reason: 'Double billing', chargeIds: ['ch1'] })
• Billing Workflow: markTransactionsReady(token, custId, { markAllUnbilled: true })
• Correction: unmarkTransactionsReady(token, custId, { transactionIds: ['tx1'] })

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.