QUICKSTART.md

Quick Start Guide - Hyperpay PTSP Node.js

This guide will help you integrate Hyperpay PTSP payment gateway into your Node.js/TypeScript application in under 5 minutes.

Installation

npm install @hyperpay/hyperpay-ptsp

Setup Environment Variables

Create a .env file in your project root:

PAYMENT_LINK_ENVIRONMENT=sandbox
PAYMENT_LINK_BASIC_AUTH_USERNAME=your-username
PAYMENT_LINK_BASIC_AUTH_PASSWORD=your-password

Basic Usage

TypeScript Example

import { HyperpayPtspService, CreatePaymentLinkRequest } from '@hyperpay/hyperpay-ptsp';

async function createPayment() {
  const service = new HyperpayPtspService();

  const request = new CreatePaymentLinkRequest();
  request.customerName = 'John Doe';
  request.customerEmail = 'john@example.com';
  request.amount = 100.00;
  request.currency = 'SAR';
  request.paymentOperation = 'pay';
  request.merchantReference = 'INV-' + Date.now();

  try {
    const response = await service.createPaymentLink(request);
    console.log('Payment Link:', response.paymentLink);
    return response.paymentLink;
  } catch (error) {
    console.error('Error:', error.message);
  }
}

createPayment();

JavaScript Example

const { HyperpayPtspService, CreatePaymentLinkRequest } = require('@hyperpay/hyperpay-ptsp');

async function createPayment() {
  const service = new HyperpayPtspService();

  const request = new CreatePaymentLinkRequest();
  request.customerName = 'John Doe';
  request.customerEmail = 'john@example.com';
  request.amount = 100.00;
  request.currency = 'SAR';
  request.paymentOperation = 'pay';
  request.merchantReference = 'INV-' + Date.now();

  try {
    const response = await service.createPaymentLink(request);
    console.log('Payment Link:', response.paymentLink);
    return response.paymentLink;
  } catch (error) {
    console.error('Error:', error.message);
  }
}

createPayment();

Express.js Integration

import express from 'express';
import { HyperpayPtspService, CreatePaymentLinkRequest } from '@hyperpay/hyperpay-ptsp';

const app = express();
app.use(express.json());

const hyperpayService = new HyperpayPtspService();

app.post('/create-payment', async (req, res) => {
  try {
    const request = new CreatePaymentLinkRequest();
    request.customerName = req.body.customerName;
    request.customerEmail = req.body.customerEmail;
    request.amount = parseFloat(req.body.amount);
    request.currency = req.body.currency;
    request.paymentOperation = 'pay';
    request.merchantReference = 'INV-' + Date.now();

    const response = await hyperpayService.createPaymentLink(request);

    res.json({
      success: true,
      paymentLink: response.paymentLink,
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message,
    });
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Check Payment Status

const service = new HyperpayPtspService();

try {
  const status = await service.getStatusByMerchantReference('INV-123456');
  
  console.log('Status:', status.responseMessage);
  console.log('Is Successful:', status.isSuccessful());
  console.log('Amount:', status.amount, status.currency);
} catch (error) {
  console.error('Error:', error.message);
}

Using Fluent Setters

const request = new CreatePaymentLinkRequest()
  .setCustomerName('Jane Doe')
  .setCustomerEmail('jane@example.com')
  .setAmount(50.00)
  .setCurrency('SAR')
  .setPaymentOperation('pay')
  .setMerchantReference('INV-' + Date.now())
  .setSendEmail(true);

const response = await service.createPaymentLink(request);

Enable Recurring Payments

const request = new CreatePaymentLinkRequest();
request.customerName = 'John Doe';
request.customerEmail = 'john@example.com';
request.amount = 100.00;
request.currency = 'SAR';
request.paymentOperation = 'pay';
request.merchantReference = 'INV-' + Date.now();
request.tokenization = 'yes'; // Enable tokenization

const response = await service.createPaymentLink(request);

// After customer completes payment, you'll receive cardToken and agreementId
// Use these for future recurring charges

Error Handling

import { HyperpayPtspException } from '@hyperpay/hyperpay-ptsp';

try {
  const response = await service.createPaymentLink(request);
} catch (error) {
  if (error instanceof HyperpayPtspException) {
    console.error('Error Code:', error.responseCode);
    console.error('HTTP Status:', error.statusCode);
    console.error('Message:', error.message);
    // Example: "[10002] Duplicate Merchant Reference | The merchant reference has already been taken."
  }
}

Next Steps

• Read the full README for detailed API reference
• Check out examples for more use cases
• View the Integration Documentation
• Switch to PAYMENT_LINK_ENVIRONMENT=production when ready to go live

Support

For questions or issues, visit GitHub Issues