ts-tpay

Type-safe wrapper for Polish payment processor tpay.

npm / tpay docs / API Reference / tpay Homepage

• Auto reauth
• Fully typed API and DTOs
• Webhook notification validation

Installation

npm install @tax1driver/ts-tpay

Quick Start

import { TPaySDK } from '@tax1driver/ts-tpay';


const tpay = new TPaySDK({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  sandbox: true  
});


const transaction = await tpay.transactions.createTransaction({
  amount: 100.50,
  description: 'Order #12345',
  payer: {
    email: '[email protected]',
    name: 'John Doe'
  },
  callbacks: {
    payerUrls: {
      success: 'https://yoursite.com/success',
      error: 'https://yoursite.com/error'
    },
    notification: {
      url: 'https://yoursite.com/webhook'
    }
  }
});


console.log('Payment URL:', transaction.transactionPaymentUrl);

Configuration

Basic Configuration

const tpay = new TPaySDK({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  sandbox: false  
});

Override Axios instance and extend config

const tpay = new TPaySDK({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  axiosInstance: userInstance,
  axiosConfig: {
    timeout: 10000,
    headers: { 'Custom-Header': 'value' }
  }
});

Configuration Options

| Option | Type | Default | Description | | --------------- | --------------------------------- | ------- | ------------------------------ | | clientId | string | - | tpay client ID | | clientSecret | string | - | tpay client secret | | sandbox | boolean \| undefined | false | sandbox environment | | | axiosInstance | AxiosInstance \| undefined | - | override axios instance | | axiosConfig | AxiosRequestConfig \| undefined | - | additional axios configuration |

API Reference

Typedoc API Reference

Common usage

Modules

Transactions

Create and manage simple merchant transactions.

const transaction = await tpay.transactions.createTransaction({
  amount: 100.50,
  description: 'Order #12345',
  payer: {
    email: '[email protected]',
    name: 'John Doe',
    phone: '+48123456789'
  },
  callbacks: {
    payerUrls: {
      success: 'https://yoursite.com/success',
      error: 'https://yoursite.com/error'
    },
    notification: {
      url: 'https://yoursite.com/webhook'
    }
  }
});


const details = await tpay.transactions.getTransaction('tr123abc');


const transactions = await tpay.transactions.getTransactions({
  pageNumber: 1,
  pageSize: 20
});


const refunds = await tpay.transactions.getRefunds('tr123abc');

BLIK

Manage BLIK aliases for recurring payments.

const alias = await tpay.blik.createAlias({
  value: '123456',  
  type: 'UID',
  label: 'Customer subscription'
});


const aliasDetails = await tpay.blik.getAlias('alias123');


await tpay.blik.deleteAlias({ value: 'alias123' });

Marketplace

Handle multi-merchant transactions with commission splits.

const marketplaceTx = await tpay.marketplace.createMarketplaceTransaction({
  amount: 100,
  description: 'Marketplace order',
  payer: {
    email: '[email protected]'
  },
  merchantTransactionId: 'order-123',
  childMerchants: [
    {
      merchantId: 'merchant1',
      amount: 80,
      commission: 10,
      description: 'Product from Merchant 1'
    },
    {
      merchantId: 'merchant2',
      amount: 20,
      commission: 2,
      description: 'Product from Merchant 2'
    }
  ]
});


const mpTx = await tpay.marketplace.getMarketplaceTransaction('mpt123');

Tokenization

Store and use payment tokens for recurring payments.

const txWithToken = await tpay.tokenization.createTransactionWithToken({
  amount: 50,
  description: 'Subscription payment',
  payer: {
    email: '[email protected]'
  },
  pay: {
    groupId: 150,  
    cardPayment: {
      card: 'token_abc123',  
      save: false
    }
  }
});


const tokens = await tpay.tokenization.getPayerTokens('payer123');

Wallet

Manage wallet balance and operations.

const balance = await tpay.wallet.getBalance();


const account = await tpay.wallet.getAccount();


const walletTx = await tpay.wallet.getTransactions({
  pageNumber: 1,
  pageSize: 50
});

Refunds

Process refunds for transactions.

const refund = await tpay.refunds.createRefund('tr123abc', {
  amount: 50.25,
  description: 'Partial refund for order #12345'
});


const refundDetails = await tpay.refunds.getRefund('refund123');

Accounts

Manage merchant accounts (marketplace functionality).

const accounts = await tpay.accounts.getAccounts({
  pageNumber: 1,
  pageSize: 20
});


const account = await tpay.accounts.getAccount('account123');


await tpay.accounts.updateAccount('account123', {
  email: '[email protected]'
});

Collect

Manage trusted bank accounts for direct debit payments.

const bankAccount = await tpay.collect.addBankAccount({
  accountNumber: 'PL61109010140000071219812874',
  name: 'John Doe'
});


const accounts = await tpay.collect.getBankAccounts();

Auth

Manually manage OAuth2 tokens (usually handled automatically).

const tokenInfo = await tpay.auth.requestToken();


const currentToken = await tpay.auth.getTokenInfo();

Notifications

Validate webhook notifications from TPay.

import express from 'express';

const app = express();

app.post('/webhook', express.raw({ type: 'application/jose' }), async (req, res) => {
  try {
    
    const notification = await tpay.notifications.validateNotification(
      req.body,  
      req.headers['x-jws-signature'] as string
    );
    
    console.log('Valid notification:', notification);
    console.log('Transaction ID:', notification.tr_id);
    console.log('Status:', notification.tr_status);
    
    res.status(200).send('OK');
  } catch (error) {
    console.error('Invalid notification:', error);
    res.status(400).send('Invalid signature');
  }
});

Webhook Notification Handling

TPay sends webhook notifications as JWS-signed tokens. Always validate signatures:

const notification = await tpay.notifications.validateNotification(
  joseToken,
  jwsSignature
);


const notification = await tpay.notifications.validateNotification(
  joseToken,
  jwsSignature,
  {
    trustedCertPath: './custom-cert.pem',  
    issuer: 'api.tpay.com'  
  }
);


switch (notification.tr_status) {
  case 'correct':
    
    break;
  case 'pending':
    
    break;
  case 'error':
    
    break;
}

Environment URLs

• Sandbox API: https://openapi.sandbox.tpay.com
• Production API: https://openapi.tpay.com

Links

• npm
• API Reference
• tpay Docs
• tpay Homepage