https://github.com/wlad1slav/wayforpay-ts-integration
wayforpay-ts-integration is a package for easy integration with the Wayforpay payment system. It allows you to create a redirect to the payment page at any point in the client-side code. After a request to your API, the package generates a form that can be automatically executed on the client-side, redirecting the user to the payment page.
https://github.com/wlad1slav/wayforpay-ts-integration
npm-package payment payment-integration typescript ukrainian wayforpay
Last synced: 6 months ago
JSON representation
wayforpay-ts-integration is a package for easy integration with the Wayforpay payment system. It allows you to create a redirect to the payment page at any point in the client-side code. After a request to your API, the package generates a form that can be automatically executed on the client-side, redirecting the user to the payment page.
- Host: GitHub
- URL: https://github.com/wlad1slav/wayforpay-ts-integration
- Owner: Wlad1slav
- Created: 2024-09-19T11:47:18.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-29T13:46:44.000Z (10 months ago)
- Last Synced: 2025-04-11T21:03:06.352Z (7 months ago)
- Topics: npm-package, payment, payment-integration, typescript, ukrainian, wayforpay
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/wayforpay-ts-integration
- Size: 202 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README-UK.md
Awesome Lists containing this project
README
# 💳 wayforpay-ts-integration
wayforpay-ts-integration — TypeScript SDK для інтеграції з платіжною системою Wayforpay. Пакет забезпечує простий доступ до API Wayforpay для обробки платежів, створення платіжних форм, отримання списку транзакцій та роботи з регулярними платежами.
🇬🇧 [English README.md](/README.md)
```bash
npm i wayforpay-ts-integration
```
## ✨ Features
- [X] Платежі
- [X] Статус платежу
- [X] Створення посилання на сторінку оплати
- [ ] Оплата в один клік
- [ ] Платіжний віджет
- [ ] Верифікація картки (Verify)
- [ ] Виставлення рахунків (Invoice)
- [ ] Поповнення карт фіз. осіб (Account2card)
- [ ] Переказ коштів на розрахунковий рахунок (Account2account)
- [X] API Отримання Списку транзакцій
- [ ] Онлайн кредитування
- [ ] Онлайн оплата таксі
- [ ] Антифрод API
- [X] Регулярні платежі
- [ ] Платіжні модулі під CMS
- [ ] Створення магазину/партнера
- [ ] Створення платіжного QR-коду
- [ ] PCI DSS
- [ ] Отримання курсів валют
## 🏪 Створення магазину в Wayforpay
Авторизуйтесь на платформі Wayforpay через [офіційний сайт](https://m.wayforpay.com/account/site/login).
Після авторизації, у боковому меню перейдіть до розділу **Налаштування магазину**. Ви побачите список ваших магазинів.
Якщо магазину ще немає, натисніть **Створити магазин**. Не забудьте вказати домен магазину. Якщо ви ще не визначились з
доменом, введіть тимчасовий.
### 🔑 Token
Після створення магазину перейдіть до його налаштувань. Там знайдіть картку з **Реквізитами мерчанта**, де ви знайдете *
*Merchant login** та **Merchant secret key**. Ці дані потрібно вказати в опціях класу `Wayforpay` або додати до файлу
`.env` у кореневій директорії вашого проекту.
- `MERCHANT_LOGIN` — логін мерчанта з налаштувань магазину
- `MERCHANT_SECRET_KEY` — секретний ключ мерчанта з налаштувань магазину
> [!CAUTION]
> **Не використовуйте** методи цього пакету на клієнтській стороні. Це може скомпрометувати ваш секретний ключ.
> Використовуйте функціонал лише на сервері (наприклад, у вашому API).
### 📦 Встановлення пакету
Після налаштування магазину, встановіть npm пакет на ваш сервер Node.js:
```bash
npm i wayforpay-ts-integration
```
## 🛠 Використання
### 📝 Платежі
Для створення платежів, Wayforpay приймає тільки прості HTTP запити з методом POST та унікальним підписом всередині. Те,
як створюється підпис та яка сама необхідна форма вам знати немає потреби, бо це все включено в функціонал цього пакету.
Все що вам варто знати:
1. користувач робить запит на сервер,
2. на сервері через наш пакет генерується HTML форма на основі кошика клієнта,
3. згенерована форма з унікальним підписом відправляється назад користувачу,
4. ви на клієнтській частині автоматично виконуєте форму для користувача АБО перенаправляєте користувача на сторінку з цією формою та скриптом для її виконання,
5. після виконання переданої форми відбувається перенаправлення на сторінку Wayforpay, де проходить оплата за замовлення.
В клас `Wayforpay` ви вказуєте дані вашого мерчанта. Метод `purchase` створює HTML-форму для оплати, яку вам треба
автоматично виконувати на клієнтській частині для користувача.
Перший параметр — це кошик користувача. Параметром повинен передаватися масив об'єктів з типом `TCartElement`.
| Property | Type | Опис |
|-----------------|--------|---------------------------|
| `quantity` | number | Кількість товару в кошику |
| `product` | object | Деталі товару |
| `product.name` | string | Назва продукту |
| `product.price` | number | Ціна продукту |
Другий параметр — це об'єкт з конфігурацією, в яку можна передати будь-яке
поле, [що підтримується Wayforpay](https://wiki.wayforpay.com/view/852102).
```typescript
import {Wayforpay, TCartElement} from "wayforpay-ts-integration";
const wayforpay = new Wayforpay({
merchantLogin: 'test_merch_n1',
merchantSecret: 'flk3409refn54t54t*FNJRET'
});
const form = await wayforpay.purchase(cart as TCartElement[], {
domain: 'www.market.ua',
currency: 'UAH'
});
```
#### Додаткова документація
- https://wiki.wayforpay.com/view/852102
#### POST приклад
```typescript
import {Wayforpay, TCartElement, TProduct, TUserCartElement} from "wayforpay-ts-integration";
const products: TProduct[] = [
{id: '1', name: "Example product 1", price: 100},
{id: '2', name: "Example product 2", price: 15}
];
app.post('/api/wayforpay/checkout', async (req: Request, res: Response) => {
const {userCart}: {
userCart: TUserCartElement[];
} = req.body;
if (userCart && userCart.length > 0) {
const cart = userCart.map(item => {
const product = products.find(product => product.id === item.id);
if (product) {
return {
quantity: item.quantity,
product
} as TCartElement;
} else {
console.error(`Product with ID ${item.id} does not exist`);
return null; // Return null for invalid products
}
}).filter(Boolean); // Filter out null values from the array
const wayforpay = new Wayforpay({
merchantLogin: process.env.MERCHANT_LOGIN as string,
merchantSecret: process.env.MERCHANT_SECRET_KEY as string,
domain: process.env.DOMAIN as string,
});
// Creates a form for a request to wayforpay
const form = await wayforpay.purchase(cart as TCartElement[], {
domain: 'example.com',
currency: 'UAH',
deliveryList: ["nova", "other"],
});
return res.send(form);
} else {
console.error('No product IDs were specified');
}
});
```
На клієнтській стороні форму необхідно вставити в DOM і автоматично виконати. Ось приклад React-компонента, який
перекидає клієнта на сторінку оплати при натисненні кнопки:
```tsx
import axios from "axios";
function GoToPaymentButton() {
const cart = [
{id: '1', quantity: 1},
{id: '4', quantity: 7},
];
const handleGoToPay = async () => {
// Here is the domain of your server and the route by which the form is received
const response = await axios.post('http://localhost:3000/api/wayforpay/checkout', {
userCart: cart
});
// Gets form's HTML from the backend
const html = await response.data;
// Check if the container already exists, if not, create it
let handlePay = document.getElementById('handlePay');
if (!handlePay) {
handlePay = document.createElement('div');
handlePay.id = 'handlePay';
document.body.appendChild(handlePay);
}
// Add the form's HTML to the container
handlePay.innerHTML = html;
// Find and submit the form
const form = document.getElementById('wayforpayForm') as HTMLFormElement;
if (form) {
form.submit(); // Completes the form
}
};
return Go to payment;
}
```
#### GET приклад
Якщо ви хочете уникати зайвих POST запитів, то ви можете зробити редірект користувача на сторінку з цією формою. Пакет вже автоматично додає в форму скрипт для її виконання, тому все що вам потрібно зробити - створити GET АПІ маршрут по якому на основі заданих в посилання параметрів буде генеруватися форма та перенаправити користувача на цей маршрут.
##### Next.js 14 з app router
```typescript
import {NextRequest, NextResponse} from "next/server";
import {TCartElement, TRequestPayment, TWayforpayAvailableCurrency, Wayforpay} from "wayforpay-ts-integration";
import {decrypt} from "@/lib/secret";
import { hookMerchant } from "@/lib/api-hooks";
export async function GET(request: NextRequest) {
const merchant = await hookMerchant('Wayforpay');
if (!merchant)
return NextResponse.json({message: 'This merchant does not exist'}, {status: 400});
const merchantData = merchant.data as {
merchantLogin: string;
};
const options = await hookOptions('Wayforpay');
let optionsData: {
currency: TWayforpayAvailableCurrency,
domain: 'example.com',
[key: string]: string
} = { currency: 'USD' };
for (const option of options) {
optionsData[option.key] = option.value;
}
const wfp = new Wayforpay({
merchantLogin: merchantData.merchantLogin,
merchantSecret: decrypt(merchant.secret)
});
const {searchParams} = new URL(request.url);
const productId = searchParams.get('id');
if (!productId)
return NextResponse.json({message: 'No required parameters found'}, {status: 400});
const product = await hookProduct(productId);
const cart: TCartElement[] = [product];
const form = await wfp.purchase(cart, optionsData as TRequestPayment);
return new Response(form, {
headers: { 'Content-Type': 'text/html' }
});
}
```
Далі вистачить просто перенаправити користувача на цей АПІ. Наприклад `window.location.href = 'https://example.com/api/public/v1/wayforpay?id=12';`.
### 📋 Отримання списку транзакцій
Запит на перелік транзакцій використовується для отримання списку транзакцій магазину за певний період часу.
Максимальний період за який ви можете приймати транзакції, становить 31 день.
#### Додаткова документація
- https://wiki.wayforpay.com/view/1736786
```typescript
const wayforpay = new Wayforpay({
merchantLogin: 'test_merch_n1',
merchantSecret: 'flk3409refn54t54t*FNJRET'
});
const transactions = await wayforpay.getTransactions();
```
### 📋 Реглярні платежі
Метод для взаємодії з регулярними платежами.
> [!NOTE]
> Інтеграція цього функціоналу розглядається індивідуально для кожного магазину. Для цього зв’яжіться з sales@wayforpay.com, вказавши merchant login, опишіть ситуацію та зазначте, що вам потрібен `MerchantPassword`.
#### Типи запитів
- `STATUS`: повертає поточний статус регулярного платежу.
- `SUSPEND`: призупиняє регулярний платіж.
- `RESUME`: відновлює регулярний платіж.
- `REMOVE`: вилучає регулярний платіж.
#### Додаткова документація
- https://wiki.wayforpay.com/view/852496
- https://wiki.wayforpay.com/view/852526
- https://wiki.wayforpay.com/view/852506
- https://wiki.wayforpay.com/view/852513
- https://wiki.wayforpay.com/view/852521
```typescript
const wayforpay = new Wayforpay({
merchantLogin: 'test_merch_n1',
merchantPassword: 'dds0a8dsa-0dasuiodshdsa0udfsn',
});
const regularPayment = await wayforpay.regularPayment(orderReference, 'STATUS');
```
### 📋 Check Status
Запит Check Status використовується для перевірки статусу платежу по `orderReference`.
#### Додаткова документація
- https://wiki.wayforpay.com/en/view/852117
```typescript
const wayforpay = new Wayforpay({
merchantLogin: 'test_merch_n1',
merchantSecret: 'flk3409refn54t54t*FNJRET'
});
const transaction = await wayforpay.checkStatus('5889_woo_w4p_1731157495');
```
## Контриб'ютинг
Вітаю внесок від усіх.
### Інструкція
Зробіть форк репозиторію
Клонуйте репозиторій
```bash
git clone https://github.com/Wlad1slav/wayforpay-ts-integration.git
```
Створіть нову гілку
```bash
git checkout -b feature/назва-функції
```
Внесіть зміни
Закомітьте зміни
```bash
git commit -m "feat: опис вашої функції"
```
Запуште зміни
```bash
git push origin feature/назва-функції
```
## Автор
[@Wlad1slav](https://github.com/Wlad1slav)
## Ліцензія
ISC