Package Exports
- @humfurie/dragonpay-nestjs
Readme
@humfurie/dragonpay-nestjs
NestJS module for the dragonpay-ph SDK. Provides DragonPayService as an injectable, fully-configured DragonPay client.
Installation
npm install dragonpay-ph @humfurie/dragonpay-nestjsQuick Start
Static Configuration (forRoot)
import { Module } from '@nestjs/common';
import { DragonPayModule } from '@humfurie/dragonpay-nestjs';
@Module({
imports: [
DragonPayModule.forRoot({
merchantId: process.env.DRAGONPAY_MERCHANT_ID!,
password: process.env.DRAGONPAY_PASSWORD!,
payoutPassword: process.env.DRAGONPAY_PAYOUT_PASSWORD,
collectUrl: process.env.DRAGONPAY_SANDBOX === 'true'
? 'https://test.dragonpay.ph/api/collect/v2'
: undefined,
}),
],
})
export class AppModule {}Async Configuration (forRootAsync)
import { Module } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { DragonPayModule } from '@humfurie/dragonpay-nestjs';
@Module({
imports: [
DragonPayModule.forRootAsync({
imports: [ConfigModule],
useFactory: (config: ConfigService) => ({
merchantId: config.getOrThrow('DRAGONPAY_MERCHANT_ID'),
password: config.getOrThrow('DRAGONPAY_PASSWORD'),
payoutPassword: config.get('DRAGONPAY_PAYOUT_PASSWORD'),
collectUrl: config.get('DRAGONPAY_SANDBOX') === 'true'
? 'https://test.dragonpay.ph/api/collect/v2'
: undefined,
}),
inject: [ConfigService],
}),
],
})
export class AppModule {}Usage
Inject DragonPayService anywhere in your application. It has the same API as DragonPayClient from dragonpay-ph.
import { Controller, Post, Body, Get, Query } from '@nestjs/common';
import { DragonPayService } from '@humfurie/dragonpay-nestjs';
@Controller('payments')
export class PaymentsController {
constructor(private readonly dragonpay: DragonPayService) {}
@Post()
async createPayment(@Body() body: { orderId: string; amount: number; email: string }) {
const txnId = this.dragonpay.generateTxnId();
return this.dragonpay.createPayment(txnId, {
amount: body.amount,
description: `Order ${body.orderId}`,
email: body.email,
procId: 'GCSH',
});
}
@Post('webhook')
async handlePostback(@Body() body: Record<string, string>) {
const result = await this.dragonpay.handlePostback(body);
if (!result.verified) {
throw new Error('Invalid postback signature');
}
// Update order status in your database
// result.txnId, result.status, result.refNo, result.amount
return 'OK';
}
@Get('return')
handleReturn(@Query() query: Record<string, string>) {
const result = this.dragonpay.parseReturnParams(query);
// Show thank you / failure page based on result.status
return result;
}
}Environment Variables
| Variable | Required | Description |
|---|---|---|
DRAGONPAY_MERCHANT_ID |
Yes | Your DragonPay merchant ID |
DRAGONPAY_PASSWORD |
Yes | Merchant password |
DRAGONPAY_PAYOUT_PASSWORD |
If using payouts | Payout API bearer token — not available in the sandbox portal; contact DragonPay directly to request payout API credentials |
DRAGONPAY_SANDBOX |
No | Set to "true" for sandbox URLs |
API
DragonPayService extends DragonPayClient from dragonpay-ph and exposes all its methods:
| Method | Description |
|---|---|
createPayment(txnId, input) |
Create a payment request |
getTransactionStatus(txnId) |
Check transaction status |
cancelTransaction(txnId) |
Cancel a pending transaction |
getAvailableProcessors(amount) |
List available processors |
handlePostback(params) |
Verify + parse collection postback |
handlePayoutPostback(params) |
Verify + parse payout postback |
parseReturnParams(params) |
Parse return URL params (UX only) |
createPayout(txnId, input) |
Create a payout |
getPayoutStatus(txnId) |
Check payout status |
generateTxnId() |
Generate a unique transaction ID |
mapProcessorCode(code) |
Map processor name to DragonPay code |
See the dragonpay-ph README for full documentation on each method, postback verification, status codes, and error handling.
Module Behavior
- Global module:
DragonPayModuleis registered as global, soDragonPayServiceis available in all modules without re-importing. - Peer dependencies: Requires
@nestjs/common^10 or ^11,dragonpay-ph>= 0.1.0, andreflect-metadata.
License
MIT