simplepay-js-sdk 0.6.1 → 0.8.0

package/README-ENG.md

@@ -0,0 +1,203 @@
+# SimplePay JS SDK
+
+[Magyar README](README.md)
+
+A lightweight utility for integrating Hungary's SimplePay payments in Node.js applications.
+
+![SimplePay Logo](simplepay_logo.jpg)
+
+Please read the [SimplePay documentation](https://simplepay.hu/fejlesztoknek) for more information.
+
+> 🫵 If this package is useful to you, please star it on GitHub.
+
+## Installation
+
+```bash
+# npm
+npm install simplepay-js-sdk
+
+# yarn
+yarn add simplepay-js-sdk
+
+# pnpm
+pnpm add simplepay-js-sdk
+```
+
+## Configuration
+
+Set the following environment variables in your `.env` file:
+
+- `SIMPLEPAY_LOGGER` If it set to `true`, it will log varibles - useful only for debugging.
+- `SIMPLEPAY_MERCHANT_KEY_HUF` Your Simplepay secret merchant key. Set `SIMPLEPAY_MERCHANT_KEY_EUR` and `SIMPLEPAY_MERCHANT_KEY_USD` for accepting EUR and USD payments.
+- `SIMPLEPAY_MERCHANT_ID_HUF` Your Simplepay merchant id. Set `SIMPLEPAY_MERCHANT_ID_EUR` and `SIMPLEPAY_MERCHANT_ID_USD` for accepting EUR and USD payments.
+- `SIMPLEPAY_PRODUCTION` If it set to `true`, it will use production environment, otherwise it will use sandbox environment.
+- `SIMPLEPAY_REDIRECT_URL` The URL of your site, where the customer will be redirected after the payment.
+
+## Usage
+
+You should create 3 endpoints, to start the payment, get the payment response and handle the IPN.
+
+### One Time Payment
+
+#### Start Payment Endpoint
+
+```typescript
+import { startPayment } from 'simplepay-js-sdk'
+
+try {
+  const response = await startPayment({
+    orderRef: 'order-12',
+    total: 1212,
+    currency: 'HUF', // optional, HUF | EUR | USD, defaults to HUF
+    customerEmail: 'rrd@webmania.cc',
+    language: 'HU', // optional, AR | BG | CS | DE | EN | ES | FR | IT | HR | HU | PL | RO | RU | SK | TR | ZH, defaults to HU
+    method: 'CARD', // optional, CARD | WIRE, defaults to CARD
+    invoice: {
+      name: 'Radharadhya Dasa',
+      country: 'HU',
+      state: 'Budapest',
+      city: 'Budapest',
+      zip: '1234',
+      address: 'Sehol u. 0',
+    },
+  })
+  return response
+} catch (error) {
+  console.error('Payment initiation failed:', error)
+  return error
+}
+```
+
+`response.paymentUrl` will contain the Simplepay payment URL, which you can redirect the customer to.
+
+#### Get Payment Response Endpoint
+
+When the customer returns from the Simplepay payment page, you need to get the payment response at your `SIMPLEPAY_REDIRECT_URL`. The url will contain 2 parameters: `r` and `s`.
+
+```typescript
+import { getPaymentResponse } from 'simplepay-js-sdk'
+
+// get "r" and "s" from the url the way you do it on your app and framework
+
+const response = getPaymentResponse(r, s)
+```
+
+`response` will have the following properties:
+
+- `responseCode`: `0` on success, or an error code
+- `transactionId`: the transaction id
+- `event`: the event type: `success` | `fail` | `timeout` | `cancel`
+- `merchantId`: the merchant id
+- `orderRef`: the order id
+
+#### IPN Endpoint
+
+Simplepay will send a `POST` request to the IPN url and you should send a response back.
+At this endpoint you should
+
+- check if the signature is valid - use `checkSignature(ipnBody, signatureHeader, SIMPLEPAY_MERCHANT_KEY_HUF)`
+- add a `receiveDate` property to the received JSON
+- calculate the new signature - use `generateSignature(responseText, SIMPLEPAY_MERCHANT_KEY_HUF)`
+- send the `response` with the new `signature`
+
+
+### Recurring Payment
+
+#### Start Recurring Payment Endpoint
+
+Here you have to use the `startRecurringPayment()` function what works the same way as the `startPayment()` function. The only difference is that you have to pass 2 additional properties: `customer` and `recurring`.
+
+```typescript
+try {
+  const response = await startRecurringPayment({
+    // ... other preoperties
+    customer: 'Radharadhya Dasa',
+    recurring: {
+      times: 3, // how many times the payment will be made, number of tokens
+      until: '2025-12-31T18:00:00+02:00', // the end date of the recurring payment - use the toISO8601DateString() helper function
+      maxAmount: 100000 // the maximum amount of the recurring payment
+    }
+  })
+}
+```
+
+The response will have an additional `tokens` property, what will contain the tokens of the registered cards.
+You are responsible to save the tokens to your database, so you can use them later to make a payment.
+
+
+#### Get Recurring Payment Response Endpoint
+
+Use the same enpoint as the one time payment.
+
+#### IPN Endpoint on card registration
+
+It works the same as the `IPN` endpoint of the one time payment.
+The response will have the same properties, and 2 additional properties:
+
+ - `cardMask`: xxxx-xxxx-xxxx-1234 - the masked card number what is registered
+ - `expiry`: 2025-01-31T00:00:00+02:00 - the expiry date of the registered card
+
+ #### Token Payment Endpoint
+
+ After a card is registered you can use the tokens to make a payment without any user intercation for example by a daily `cron`
+
+```typescript
+import { startTokenPayment } from 'simplepay-js-sdk'
+
+// TODO: get payment data from your database, where you saved the tokens
+
+const payment = {
+  token: '1234567890123456',
+  total: 1212,
+  currency: 'HUF' as Currency,
+  customer: 'Radharadhya Dasa',
+  customerEmail: 'rrd@webmania.cc',
+  invoice: {
+    name: 'Radharadhya Dasa',
+    country: 'HU',
+    state: 'Budapest',
+    city: 'Budapest',
+    zip: '1234',
+    address: 'Sehol u. 0',
+  },
+}
+
+try {
+  const response = await startTokenPayment({
+    orderRef: Date.now().toString(),
+    language: 'HU',
+    method: 'CARD', // must be CARD
+    ...payment,
+  })
+  return response
+} catch (error) {
+  console.error('Token payment initiation failed:', error)
+  return error
+}
+```
+
+#### Card Cancelation
+
+Paying customers should be able to delete their registered card on the website.
+To do this, use the `cancelCard` function. Use SimplePay transaction id of the card registration transaction as `cardId`.
+
+```typescript
+import { cancelCard } from 'simplepay-js-sdk'
+
+try {
+  const response = await cancelCard(cardId)
+  
+  if (response.status == 'DISABLED') {
+    // The card has been successfully deleted
+    // TODO: delete the unused tokens and the card from the database
+  }
+  return response
+} catch (error) {
+  console.error('Card deletion failed:', error)
+  return error
+}
+```
+
+## License
+
+MIT

package/README.md

@@ -1,12 +1,16 @@
 # SimplePay JS SDK
 
-A lightweight utility for integrating Hungary's SimplePay payments in Node.js applications.
+[English README](README-ENG.md)
+
+Egy pehelysúlyú segédprogram a magyarországi SimplePay fizetések integrálásához Node.js alkalmazásokban.
 
 ![SimplePay Logo](simplepay_logo.jpg)
 
-Please read the [SimplePay documentation](https://simplepay.hu/fejlesztoknek) for more information.
+További információkért kérlek, olvasd el a [SimplePay dokumentációt](https://simplepay.hu/fejlesztoknek).
+
+> 🫵 Ha a csomag hasznos a számodra, akkor ne feletjs el rányomni a star-ra GitHub-on.
 
-## Installation
+## Telepítés
 
 ```bash
 # npm
@@ -19,21 +23,23 @@ yarn add simplepay-js-sdk
 pnpm add simplepay-js-sdk
 ```
 
-## Configuration
+## Konfiguráció
+
+Állítsd be a következő környezeti változókat a `.env` fájlban:
 
-Set the following environment variables in your `.env` file:
+- `SIMPLEPAY_LOGGER` Ha `true`-ra van állítva, naplózza a változókat - csak hibakereséshez hasznos.
+- `SIMPLEPAY_MERCHANT_KEY_HUF` A te SimplePay titkos kereskedői kulcsod. Állítsd be a `SIMPLEPAY_MERCHANT_KEY_EUR` és `SIMPLEPAY_MERCHANT_KEY_USD` értékeket EUR és USD fizetések elfogadásához.
+- `SIMPLEPAY_MERCHANT_ID_HUF` A te SimplePay kereskedői azonosítód. Állítsd be a `SIMPLEPAY_MERCHANT_ID_EUR` és `SIMPLEPAY_MERCHANT_ID_USD` értékeket EUR és USD fizetések elfogadásához.
+- `SIMPLEPAY_PRODUCTION` Ha `true`-ra van állítva, éles környezetet használ, egyébként teszt környezetet.
+- `SIMPLEPAY_REDIRECT_URL` A te weboldalad URL-je, ahova a vásárló átirányításra kerül a fizetés után.
 
-- `SIMPLEPAY_LOGGER` If it set to `true`, it will log varibles - useful only for debugging.
-- `SIMPLEPAY_MERCHANT_KEY_HUF` Your Simplepay secret merchant key. Set `SIMPLEPAY_MERCHANT_KEY_EUR` and `SIMPLEPAY_MERCHANT_KEY_USD` for accepting EUR and USD payments.
-- `SIMPLEPAY_MERCHANT_ID_HUF` Your Simplepay merchant id. Set `SIMPLEPAY_MERCHANT_ID_EUR` and `SIMPLEPAY_MERCHANT_ID_USD` for accepting EUR and USD payments.
-- `SIMPLEPAY_PRODUCTION` If it set to `true`, it will use production environment, otherwise it will use sandbox environment.
-- `SIMPLEPAY_REDIRECT_URL` The URL of your site, where the customer will be redirected after the payment.
+## Használat
 
-## Usage
+Három végpontot kell létrehoznia: egyet a fizetés indításához, egyet a fizetési válasz fogadásához és egyet az IPN kezeléséhez.
 
-You should create 3 endpoints, to start the payment, get the payment response and handle the IPN.
+### Egyszeri fizetés
 
-### Start Payment Endpoint
+#### Fizetés indítása végpont
 
 ```typescript
 import { startPayment } from 'simplepay-js-sdk'
@@ -42,10 +48,10 @@ try {
   const response = await startPayment({
     orderRef: 'order-12',
     total: 1212,
-    currency: 'HUF', // optional, HUF | EUR | USD, defaults to HUF
+    currency: 'HUF', // opcionális, HUF | EUR | USD, alapértelmezett: HUF
     customerEmail: 'rrd@webmania.cc',
-    language: 'HU', // optional, AR | BG | CS | DE | EN | ES | FR | IT | HR | HU | PL | RO | RU | SK | TR | ZH, defaults to HU
-    method: 'CARD', // optional, CARD | WIRE, defaults to CARD
+    language: 'HU', // opcionális, AR | BG | CS | DE | EN | ES | FR | IT | HR | HU | PL | RO | RU | SK | TR | ZH, alapértelmezett: HU
+    method: 'CARD', // opcionális, CARD | WIRE, alapértelmezett: CARD
     invoice: {
       name: 'Radharadhya Dasa',
       country: 'HU',
@@ -57,43 +63,139 @@ try {
   })
   return response
 } catch (error) {
-  console.error('Payment initiation failed:', error)
+  console.error('Fizetés indítása sikertelen:', error)
   return error
 }
 ```
 
-`response.paymentUrl` will contain the Simplepay payment URL, which you can redirect the customer to.
+A `response.paymentUrl` tartalmazza a SimplePay fizetési URL-t, ahova a vásárlót átirányíthatja.
 
-### Get Payment Response Endpoint
+#### Fizetési válasz fogadása végpont
 
-When the customer returns from the Simplepay payment page, you need to get the payment response at your `SIMPLEPAY_REDIRECT_URL`. The url will contain 2 parameters: `r` and `s`.
+Amikor a vásárló visszatér a SimplePay fizetési oldalról, a fizetési választ a `SIMPLEPAY_REDIRECT_URL` címen kell fogadni. Az URL két paramétert tartalmaz: `r` és `s`.
 
 ```typescript
 import { getPaymentResponse } from 'simplepay-js-sdk'
 
-// get "r" and "s" from the url the way you do it on your app and framework
+// az "r" és "s" paraméterek kinyerése az URL-ből az alkalmazásod és keretrendszerének megfelelően
 
 const response = getPaymentResponse(r, s)
 ```
 
-`response` will have the following properties:
+A `response` a következő tulajdonságokkal rendelkezik:
+
+- `responseCode`: `0` siker esetén, vagy hibakód
+- `transactionId`: a tranzakció azonosítója
+- `event`: az esemény típusa: `success` | `fail` | `timeout` | `cancel`
+- `merchantId`: a kereskedő azonosítója
+- `orderRef`: a rendelés azonosítója
+
+#### IPN végpont
+
+A SimplePay `POST` kérést küld az IPN URL-re, és válaszolnunk kell rá.
+Ennél a végpontnál a következőket kell tenned:
+
+- ellenőrizd az aláírás érvényességét - használd a `checkSignature(ipnBody, signatureHeader, SIMPLEPAY_MERCHANT_KEY_HUF)` függvényt
+- adj hozzá egy `receiveDate` tulajdonságot a kapott JSON-hoz
+- számítsa ki az új aláírást - használd a `generateSignature(responseText, SIMPLEPAY_MERCHANT_KEY_HUF)` függvényt
+- küldd el a `response`-t az új `signature`-rel
+
+### Ismétlődő fizetés
+
+#### Ismétlődő fizetés indítása végpont
+
+Itt a `startRecurringPayment()` függvényt kell használnod, ami ugyanúgy működik, mint a `startPayment()`. Az egyetlen különbség, hogy két további tulajdonságot kell megadni: `customer` és `recurring`.
+
+```typescript
+try {
+  const response = await startRecurringPayment({
+    // ... egyéb tulajdonságok
+    customer: 'Radharadhya Dasa',
+    recurring: {
+      times: 3, // hányszor történik meg a fizetés, tokenek száma
+      until: '2025-12-31T18:00:00+02:00', // az ismétlődő fizetés végdátuma - használd a toISO8601DateString() segédfüggvényt
+      maxAmount: 100000 // az ismétlődő fizetés maximális összege
+    }
+  })
+}
+```
+
+A válasz egy további `tokens` tulajdonsággal rendelkezik, ami tartalmazza a regisztrált kártyák tokenjeit.
+A te dolgod a tokenek mentése az adatbázisba, hogy később használhasd őket fizetéshez.
+
+#### Ismétlődő fizetési válasz fogadása végpont
+
+Használd ugyanazt a végpontot, mint az egyszeri fizetésnél.
+
+#### IPN végpont kártyaregisztrációnál
+
+Ugyanúgy működik, mint az egyszeri fizetés `IPN` végpontja.
+A válasz ugyanazokkal a tulajdonságokkal rendelkezik, és 2 további tulajdonsággal:
 
-- `responseCode`: `0` on success, or an error code
-- `transactionId`: the transaction id
-- `event`: the event type: `success` | `fail` | `timeout` | `cancel`
-- `merchantId`: the merchant id
-- `orderRef`: the order id
+- `cardMask`: xxxx-xxxx-xxxx-1234 - a regisztrált kártya maszkolt száma
+- `expiry`: 2025-01-31T00:00:00+02:00 - a regisztrált kártya lejárati dátuma
 
-### IPN Endpoint
+#### Tokenes fizetés
 
-Simplepay will send a `POST` request to the IPN url and you should send a response back.
-At this endpoint you should
+Miután egy kártya regisztrálva van, használhatod a tokeneket fizetéshez felhasználói interakció nélkül, például napi `cron` feladattal
 
-- check if the signature is valid - use `checkSignature(ipnBody, signatureHeader, SIMPLEPAY_MERCHANT_KEY_HUF)`
-- add a `receiveDate` property to the received JSON
-- calculate the new signature - use `generateSignature(responseText, SIMPLEPAY_MERCHANT_KEY_HUF)`
-- send the `response` with the new `signature`
+```typescript
+import { startTokenPayment } from 'simplepay-js-sdk'
+
+// TODO: fizetési adatok lekérése az adatbázisból, ahol a tokeneket tárolod
+
+const payment = {
+  token: '1234567890123456',
+  total: 1212,
+  currency: 'HUF' as Currency,
+  customer: 'Radharadhya Dasa',
+  customerEmail: 'rrd@webmania.cc',
+  invoice: {
+    name: 'Radharadhya Dasa',
+    country: 'HU',
+    state: 'Budapest',
+    city: 'Budapest',
+    zip: '1234',
+    address: 'Sehol u. 0',
+  },
+}
+
+try {
+  const response = await startTokenPayment({
+    orderRef: Date.now().toString(),
+    language: 'HU',
+    method: 'CARD', // kötelezően CARD
+    ...payment,
+  })
+  return response
+} catch (error) {
+  console.error('Token fizetés indítása sikertelen:', error)
+  return error
+}
+```
+
+#### Kártya törlése
+
+A fizető ügyfelek számára lehetővé kell tenni, hogy a honlapodon belépve törölni tudja a regisztrált kártyáját.
+Ehhez használd a `cancelCard` függvényt. `cardId`-ként a kártya regisztrációs tranzakció SimplePay azonosítóját kell megadnod.
+
+```typescript
+import { cancelCard } from 'simplepay-js-sdk'
+
+try {
+  const response = await cancelCard(cardId)
+  
+  if (response.status == 'DISABLED') {
+    // A kártya sikeresen törölve
+    // TODO: a fel nem használt tokenek és a kártya törlése az adatbázisból
+  }
+  return response
+} catch (error) {
+  console.error('Kártya törlése sikertelen:', error)
+  return error
+}
+```
 
-## License
+## Licenc
 
-MIT
+MIT

package/dist/index.d.ts

@@ -1,29 +1,18 @@
+export declare const cardCancel: (cardId: string) => Promise<SimplePayCardCancelResponse>;
+
 export declare const checkSignature: (responseText: string, signature: string, merchantKey: string) => boolean;
 
 declare const CURRENCIES: readonly ["HUF", "EUR", "USD"];
 
-declare type Currency = typeof CURRENCIES[number];
+export declare type Currency = typeof CURRENCIES[number];
 
 export declare const generateSignature: (body: string, merchantKey: string) => string;
 
-export declare const getCurrencyFromMerchantId: (merchantId: string) => "HUF" | "EUR" | "USD";
-
-export declare const getPaymentResponse: (r: string, signature: string) => {
-    responseCode: number;
-    transactionId: string;
-    event: "success" | "fail" | "timeout" | "cancel";
-    merchantId: string;
-    orderRef: string;
-};
+export declare const getPaymentResponse: (r: string, signature: string) => SimplePayResult;
 
-export declare const getSimplePayConfig: (currency: Currency) => {
-    MERCHANT_KEY: string | undefined;
-    MERCHANT_ID: string | undefined;
-    API_URL: string;
-    SDK_VERSION: string;
-};
+declare type ISO8601DateString = string;
 
-declare type Language = typeof LANGUAGES[number];
+export declare type Language = typeof LANGUAGES[number];
 
 declare const LANGUAGES: readonly ["AR", "BG", "CS", "DE", "EN", "ES", "FR", "IT", "HR", "HU", "PL", "RO", "RU", "SK", "TR", "ZH"];
 
@@ -46,7 +35,32 @@ declare interface PaymentData {
     };
 }
 
-declare type PaymentMethod = 'CARD' | 'WIRE';
+export declare type PaymentMethod = 'CARD' | 'WIRE';
+
+declare interface Recurring {
+    times: number;
+    until: ISO8601DateString;
+    maxAmount: number;
+}
+
+declare interface RecurringPaymentData extends PaymentData {
+    customer: string;
+    recurring: Recurring;
+}
+
+declare interface SimplePayCardCancelResponse {
+    salt: string;
+    merchant: string;
+    cardId: string;
+    status: 'DISABLED';
+    expiry: string;
+}
+
+declare type SimplePayEvents = 'SUCCESS' | 'FAIL' | 'TIMEOUT' | 'CANCEL';
+
+declare interface SimplePayRecurringResponse extends SimplePayResponse {
+    tokens: string[];
+}
 
 declare interface SimplePayResponse {
     salt: string;
@@ -54,12 +68,36 @@ declare interface SimplePayResponse {
     orderRef: string;
     currency: Currency;
     transactionId: string;
-    timeout: string;
+    timeout: ISO8601DateString;
     total: string;
     paymentUrl: string;
     errorCodes?: string[];
 }
 
+declare interface SimplePayResult {
+    responseCode: number;
+    transactionId: string;
+    event: SimplePayEvents;
+    merchantId: string;
+    orderRef: string;
+    tokens?: string[];
+}
+
+declare interface SimplePayTokenResponse extends Omit<SimplePayResponse, 'paymentUrl' | 'timeout'> {
+}
+
 export declare const startPayment: (paymentData: PaymentData) => Promise<SimplePayResponse>;
 
+export declare const startRecurringPayment: (paymentData: RecurringPaymentData) => Promise<SimplePayRecurringResponse>;
+
+export declare const startTokenPayment: (paymentData: TokenPaymentData) => Promise<SimplePayTokenResponse>;
+
+export declare const toISO8601DateString: (date: Date) => ISO8601DateString;
+
+declare interface TokenPaymentData extends Omit<PaymentData, 'method'> {
+    method: 'CARD';
+    customer: string;
+    token: string;
+}
+
 export { }