💳 wayforpay-ts-integration

wayforpay-ts-integration — a TypeScript SDK for integrating with the Wayforpay payment system. The package provides easy access to the Wayforpay API for processing payments, creating payment forms, retrieving transaction lists, and regular payments.

🇺🇦 Українська README.md

npm i wayforpay-ts-integration

✨ Features

• [X] Payments
• [X] Check Status
• [X] Creating a link to the checkout page
• [ ] One-Click Payment
• [ ] Payment Widget
• [ ] Card Verification (Verify)
• [ ] Invoicing (Invoice)
• [ ] Card Top-Up for Individuals (Account2card)
• [ ] Funds Transfer to Bank Account (Account2account)
• [X] API for Transaction List Retrieval
• [ ] Online Lending
• [ ] Online Taxi Payment
• [ ] Anti-Fraud API
• [X] Regular Payments
• [ ] Payment Modules for CMS
• [ ] Store/Partner Creation
• [ ] Payment QR Code Creation
• [ ] PCI DSS
• [ ] Currency Rates Retrieval

🏪 Creating a Store in Wayforpay

Log in to the Wayforpay platform through the official website.

After logging in, go to the Store Settings section in the sidebar. You will see a list of your stores. If there is no store yet, click Create Store. Don't forget to specify the store's domain. If you haven't decided on a domain yet, enter a temporary one.

🔑 Tokens

After creating the store, go to its settings. There, find the Merchant Details section, where you will see the Merchant login and Merchant secret key. You need to specify these details in the options for the Wayforpay class or add them to the .env file in the root directory of your project.

• MERCHANT_LOGIN — the merchant login from the store settings
• MERCHANT_SECRET_KEY — the merchant secret key from the store settings

[!CAUTION] Do not use the methods of this package on the client side. This may compromise your secret key. Use the functionality only on the server side (e.g., in your API).

📦 Installing the Package

After setting up the store, install the npm package on your Node.js server:

npm i wayforpay-ts-integration

🛠 Usage

📝 Payments

To create payments, Wayforpay accepts only simple HTTP requests with the POST method and a unique signature included. You don’t need to worry about how the signature is generated or the specific format required, as this is all handled by this package’s functionality.

Here’s what you need to know:

1. The user sends a request to the server.
2. The server uses our package to generate an HTML form based on the client’s cart.
3. The generated form, with a unique signature, is sent back to the user.
4. You automatically execute the form for the user on the client side OR redirect the user to a page with this form and a script for its execution.
5. After the form is submitted, the user is redirected to the Wayforpay page for order payment.

In the Wayforpay class, you specify your merchant’s data. The purchase method generates an HTML form for payment, which should be automatically executed on the client side for the user.

The first parameter is the user’s cart. It should be passed as an array of objects with the TCartElement type.

| Property | Type | Description | |-----------------|--------|------------------------------------| | quantity | number | Quantity of products in the basket | | product | object | Product details | | product.name | string | Product name | | product.price | number | Product price |

The second parameter is a configuration object, where you can pass any field supported by Wayforpay.

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'
});

Additional documentation

• https://wiki.wayforpay.com/view/852102

POST example

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,
    });

    // 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');
  }
});

On the client side, the form needs to be inserted into the DOM and automatically executed. Here is an example of a React component that redirects the client to the payment page upon clicking a button:

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 <button onClick={handleGoToPay} type="button">Go to payment</button>;
}

GET example

If you want to avoid unnecessary POST requests, you can redirect the user to a page with this form. The package automatically adds a script to the form to handle its submission, so all you need to do is create a GET API route that generates the form based on the parameters specified in the URL and redirect the user to this route.

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' }
    });
}

Next, it's enough to simply redirect the user to this API. For example: window.location.href = 'https://example.com/api/public/v1/wayforpay?id=12';.

📋 Retrieving the List of Transactions

A transaction list request is used to obtain a list of store transactions for a specific period.

The maximum period for which you can receive transactions is 31 days.

Additional documentation

• https://wiki.wayforpay.com/view/1736786

const wayforpay = new Wayforpay({
    merchantLogin: 'test_merch_n1',
    merchantSecret: 'flk3409refn54t54t*FNJRET'
});

const transactions = await wayforpay.getTransactions();

📋 Regular Payments

A method for interacting with regular payments.

[!NOTE]
The integration of this functionality is considered individually for each store. To proceed, contact [email protected], specifying the merchant's login, describing the situation, and mentioning that you need a MerchantPassword.

Request types

• STATUS: Returns the current status of the regular payment.
• SUSPEND: Suspends the regular payment.
• RESUME: Resumes the regular payment.
• REMOVE: Removes the regular payment.

Additional documentation

• 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

const wayforpay = new Wayforpay({
    merchantLogin: 'test_merch_n1',
    merchantPassword: 'dds0a8dsa-0dasuiodshdsa0udfsn',
});

const regularPayment = await wayforpay.regularPayment(orderReference, 'STATUS');

📋 Check Status

Check Status request is used for checking of payment status on orderReference.

The request is to be formed at the side of merchant and to be transferred through POST method to URL https://api.wayforpay.com/api.

Additional documentation

• https://wiki.wayforpay.com/en/view/852117

const wayforpay = new Wayforpay({
    merchantLogin: 'test_merch_n1',
    merchantSecret: 'flk3409refn54t54t*FNJRET'
});

const transaction = await wayforpay.checkStatus('5889_woo_w4p_1731157495');

Contributing

Contributions from everyone are welcome.

Instructions

Fork the repository

Clone the repository

git clone https://github.com/Wlad1slav/wayforpay-ts-integration.git

Create a new branch

git checkout -b feature/feature-name

Make your changes

Commit your changes

git commit -m "feat: description of your feature"

Push your changes

git push origin feature/feature-name

Author

@Wlad1slav

License

ISC