Nimble Polyglot Microcosm

    qiwi-sdk
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.3 • Public • Published

    QIWI SDK

    Typed QIWI Wallet SDK for NodeJS. Supported API's: Personal & P2P Bill Payments

    QIWI SDK

    Test Status Downloads last commit codecov GitHub qiwi-sdk Known Vulnerabilities Quality npm license MIT Size Codacy Badge

    👅 Язык

    Весь JSDoc библиотеки на русском языке, как и большая часть документации. Основной README.md файл на английском потому что:

    1. NPM лучше индексирует текст на английском + хочется чтобы не русскоговорящие люди, нашедшие эту библиотеку на NPM не пугались того, что всё на Русском.
    2. Английский - это язык из которого пошли программистские термины, в том числе те, что нельзя перевести. (например: Contributing)

    👉 Документация на Русском 🇷🇺 👈

    Language: Русский | English

    🍬 Why use this lib?

    1. Full. Covers the following APIs:
    2. Simple. All methods are named as in QIWI documentation and collected into subclasses. All methods have JSDoc comments.
    3. Reliable. The library is written in TypeScript and covered by tests.
    4. Secure. The library has only 1 dependency (axios) and is constantly scanned by Code QL and Snyk for vulnerabilities.
    5. Compatible. Code from version 1.1.0 (18 Jan. 2020) will work on version 4.0.0 (26 May 2022) with little changes. Also qiwi-sdk provides classes to make migration from similar libs effortless.
    6. Powerful. Supports http & socks proxy out of the box, and rarely used APIs:
      • Personal Webhooks;
      • P2P payment method blocking;
      • "Qiwi Master" Card API.
      • Express integration out of the box
    7. Cross Platform. Works in browser

    Language: Русский | English

    📦 Installation

    • Using npm
      npm i qiwi-sdk
    • Using Yarn
      yarn add qiwi-sdk
    • Using pnpm
      pnpm add qiwi-sdk

    Language: Русский | English

    🛠️ Usage

    Import

    From the library you can import all the APIs separately, because use cases are different.

    • CommonJS (default for Node JS)

      const { P2p, Wallet, Detector } = require("qiwi-sdk");
    • TypeScript or ES Modules

      import { P2p, Wallet, Detector } from "qiwi-sdk";

    Documentation

    👉 View API Reference 👈

    The table shows the currently implemented APIs.

    Class (Legacy v2) is a compatible class only for those who are upgrading from version 2. The rest are advised to use the new version of the API - Class v3.

    API Overview

    Class (v3) Class (Legacy v2) Documentation by QIWI Recommended var name
    Wallet Personal https://developer.qiwi.com/en/qiwi-wallet-personal wallet (or qiwi)
    P2p P2P https://developer.qiwi.com/en/p2p-payments p2p
    P2p - https://developer.qiwi.com/en/bill-payments p2p (or payments)
    Detector DetectorCompat https://developer.qiwi.com/en/qiwi-wallet-personal/#search-providers detector

    To see detailed documentation on a class, click on its name.

    Migration

    1. Migration from version 2 to 3;
    2. Migration from version 1 to 2 (just in case);
    3. Migration from node-qiwi;
    4. Migration from @qiwi/bill-payments-node-js-sdk.

    Instantiation

    const { Wallet, P2p, Detector } = require("qiwi-sdk");
    
    // ✅ - The right way (since v3.0.0)
    const wallet = Wallet.create(process.env.QIWI_TOKEN, process.env.QIWI_WALLET);
    const p2p = P2p.create(process.env.QIWI_SECRET_KEY, process.env.QIWI_PUBLIC_KEY);
    const detect = Detector.create();
    
    // ✅ - Also right way (but since v3.2.0)
    const wallet = new Wallet({
      token: process.env.QIWI_TOKEN,
      walletId: process.env.QIWI_WALLET
    });
    const p2p = new P2p({
      secretKey: process.env.QIWI_SECRET_KEY,
      publicKey: process.env.QIWI_PUBLIC_KEY
    });
    const detect = new Detector();

    Environment variables

    The following environment variables were used in this example. It's recommended to store all data for API access in environment variables or in another protected place, but not in the code.

    Name Type Description
    QIWI_TOKEN String(32 chars) - Hex Qiwi token got on https://qiwi.com/api
    QIWI_WALLET String(10-16 chars) - Digits Wallet's phone number
    QIWI_SECRET_KEY и QIWI_PUBLIC_KEY Strings Key pair created on https://qiwi.com/p2p-admin/transfers/api

    Examples

    Getting info about wallet

    const wallet = Wallet.create(process.env.QIWI_TOKEN);
    
    wallet.personProfile.getCurrent().then(console.log);
    // => { contractInfo: {...}, authInfo: {...}, userInfo: {...} }

    Sending payment

    const wallet = Wallet.create(process.env.QIWI_TOKEN);
    
    // 100 RUB from RUB account to QIWI (99) `79123456789` including commission
    // All above can be configured
    wallet.payments.quickPay({
      amount: 100,
      account: "79123456789"
    });

    Using P2P

    const p2p = P2p.create(process.env.QIWI_SECRET_KEY);
    
    p2p.bills
      .create({
        amount: {
          value: 1000,
          currency: P2p.Currency.RUB
        },
        successUrl: "https://youtu.be/dQw4w9WgXcQ"
      })
      .then(console.log);
    
    // => { payUrl: 'https://oplata.qiwi.com/...' }

    Using Proxy

    const { SocksProxyAgent } = require("socks-proxy-agent");
    
    const wallet = Wallet.create(process.env.QIWI_TOKEN);
    wallet.agent = new SocksProxyAgent("socks://login:password@host:port");
    
    // do work here
    
    // Remember to dispose agent
    wallet.agent = undefined;

    Express integration

    const p2p = P2p.create(process.env.QIWI_SECRET_KEY);
    const app = express();
    
    app.post(
      "/webhook/qiwi",
      p2p.notificationMiddleware({}, (req, res) => {
        // Bill body
        console.log(req.body);
    
        // { "siteId": "9hh4jb-00", "billId": "cc961e8d-d4d6-4f02-b737-2297e51fb48e", ... }
      })
    );
    
    app.use((error, req, res, next) => {
      if (error instanceof P2pBillNotificationError) {
        // Somebody sent invalid notification
        console.log(error);
      }
    
      return next();
    });

    Full examples

    1. 🥝 Getting info about wallet
    2. 📬 Sending payment
    3. 🛠️ Using P2P api
    4. 🔐 Getting wallet limits (using ESM)
    5. 🤖 Telegram bot with direct payments (by wallet phone number)
    6. 🖥️ Shop on Express
    7. 🌐 Using proxy

    Language: Русский | English

    🎩 About the Project

    License

    Distributed under the MIT License. See LICENSE.txt for more information.

    FOSSA Status

    Project Goals

    • [ ] Cover all APIs (both for persons & legal entities)
      • [x] API QIWI Wallet
      • [ ] Payments
      • [ ] Payouts
    • [x] Keep versions backwards compatible
      • [x] v2 и v3
      • [x] v1 и v2
    • [x] Ensure maximum reliability and code quality
      • [x] Types: TypeScript
      • [x] Tests: Jest, Codecov
      • [x] Auto-tests in the repository: Github Actions
      • [x] Linking: Eslint, Prettier, Editorconfig
      • [x] Security: Eslint Plugin, Code QL, manual check in Snyk

    Contributing

    1. ⁉️ Do not hesitate to create Issues
    2. 🛠️ If you want to contribute to code, follow CONTRIBUTING.md
    3. 💸 Also please donate 👉 https://qiwi.com/n/ALEXXGRIB
    4. 🌟 Or give this repo a star, if you liked this lib

    Support

    You can write issue, or if i am slow to answer it, you can DM me in

    Telegram: @AlexXanderGrib

    💜 YooMoney package

    Interested in P2P acquiring in Russia?

    Check out my other SDK for YooMoney (formerly Yandex.Money) 👉 github.com/AlexXanderGrib/yoomoney-sdk

    Language: Русский | English

    Install

    npm i qiwi-sdk

    DownloadsWeekly Downloads

    64

    Version

    4.0.3

    License

    MIT

    Unpacked Size

    4.11 MB

    Total Files

    594

    Last publish

    Collaborators

    • alexxgrib