Numerous Philanthropic Misanthropes

    @a2seven/yoo-checkout
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.2 • Public • Published

    Yoo.Checkout API SDK (unofficial)

    A2SEVEN

    npm version

    npm downloads

    testing

    license

    support us

    README на русском!

    Yoo.Checkout - a universal solution for working with online payments. The Yoo.Checkout API is built on REST-principles, works with real objects and has predictable behavior. Using this API, you can send payment requests, save payment information for repeated charges (and include auto payments), make refunds and much more. The API uses HTTP as the main protocol, which means it is suitable for development in any programming language that can work with HTTP libraries (for example, cURL). Authentication uses Basic Auth, so you can make your first request directly from the browser. The API supports POST and GET requests. POST requests use JSON arguments, GET requests work with query strings. The API always returns a response in JSON format, regardless of the type of request.

    Authentication

    To authenticate requests you need to use HTTP Basic Auth. In the headers of the requests as a user name you need to pass the ID of your store in YooKassa, as a password - your secret key (it must be generated and activated by the password from the sms)

    Example request with authentication

    curl https://api.yookassa.ru/v3/payments/{payment_id} \
      -u <shopId>:<secretKey>

    Idempotency

    In API context, idempotency means that multiple requests are handled the same way as a single request. It means that if you receive a repeated request with the same parameters, you will get the result of the original request in your response. This behavior helps to avoid undesirable repetition of transactions. For example, if there is a problem with the network and the connection is broken while making a payment, you can safely repeat the request as many times as you want. GET requests are idempotent by default because they have no undesirable consequences. The Idempotence-Key header (or idempotence key) is used to ensure the idempotency of POST requests.

    Example of a query with an idempotent key

    curl https://api.yookassa.ru/v3/refunds \
      -X POST \
      -u <shopId>:<secretKey> \
      -H 'Idempotence-Key: <Idempotency key>' \
      -H 'Content-Type: application/json' \
      -d '{
            "amount": {
              "value": "2.00",
              "currency": "RUB"
            },
            "payment_id": "215d8da0-000f-50be-b000-0003308c89be"
          }'

    If you repeat a request with the same data and the same key, the API processes it as a repeat request. If the data in the request is the same and the idempotence key is different, the request is executed as a new one. You can pass any value unique to that operation on your side in the Idempotence-Key header. We recommend using a V4 UUID. YooKassa provides idempotence for 24 hours after the first request, then a second request will be processed as a new one.

    Synchronicity

    YooKassa processes the received request immediately and returns the result of processing ("success" or "failure"). If an exact response cannot be given within 30 seconds, e.g. due to a problem on the acquirer's side, YooKassa will return HTTP code 500 and try to cancel the operation. To find out the final result of the request, repeat the request with the same data and the same idempotent key. The recommended frequency of repetitions is once per minute, until YooKassa reports a response other than HTTP 500.

    HTTP response codes

    If the request is processed successfully, the API will return the HTTP code 200 and the response body. If an error occurs during processing, API will return the error object and standard HTTP code.

    HTTP CODE ERROR CODE DESCRIPTION
    400 invalid_request, not_supported Incorrect request. Most often this status is issued due to a violation of the rules of interaction with the API.
    401 invalid_credentials [Basic Auth] Your YooKassa account ID or secret key (authentication username and password) is invalid. [OAuth 2.0] Invalid OAuth token: it is invalid, out of date, or has been revoked. Request the token again.
    403 forbidden The secret key or OAuth token is correct, but lacks permissions to complete the transaction.
    404 not_found Resource not found.
    429 too_many_requests The limit of requests per time unit has been exceeded. Try reducing the intensity of the requests.
    500 internal_server_error Technical problems on the side of YooKasa. The result of the request processing is unknown. Repeat the request later with the same idempotency key. It is recommended to repeat the request at intervals of once a minute until YooKassa reports the result of operation processing.

    Example error response body

      {
        "type": "error",
        "id": "ab5a11cd-13cc-4e33-af8b-75a74e18dd09",
        "code": "invalid_request",
        "description": "Idempotence key duplicated",
        "parameter": "Idempotence-Key"
      }

    SDK Error Response

    ErrorResponse {
        "type": "error",
        "id": "ab5a11cd-13cc-4e33-af8b-75a74e18dd09",
        "code": "invalid_request",
        "description": "Idempotence key duplicated",
        "parameter": "Idempotence-Key"
        "errorCode": 401
    }

    Reference

    YooKassa API page

    Installation

    npm install @a2seven/yoo-checkout

    Getting started

    import { YooCheckout } from '@a2seven/yoo-checkout'; // OR const { YooCheckout } = require('@a2seven/yoo-checkout');
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });

    Docs

    Create payment

    import { YooCheckout, ICreatePayment  } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });
    
    const idempotenceKey = '02347fc4-a1f0-49db-807e-f0d67c2ed5a5';
    
    const createPayload: ICreatePayment = {
        amount: {
            value: '2.00',
            currency: 'RUB'
        },
        payment_method_data: {
            type: 'bank_card'
        },
        confirmation: {
            type: 'redirect',
            return_url: 'test'
        }
    };
    
    try {
        const payment = await checkout.createPayment(createPayload, idempotenceKey);
        console.log(payment)
    } catch (error) {
         console.error(error);
    }

    Get payment

    import { YooCheckout } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });
    
    const paymentId = '21966b95-000f-50bf-b000-0d78983bb5bc';
    
    try {
        const payment = await checkout.getPayment(paymentId);
        console.log(payment)
    } catch (error) {
         console.error(error);
    }

    Capture payment

    import { YooCheckout, ICapturePayment } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });
    
    const paymentId = '21966b95-000f-50bf-b000-0d78983bb5bc';
    
    const idempotenceKey = '02347fc4-a1f0-49db-807e-f0d67c2ed5a5';
    
    const capturePayload: ICapturePayment = {
        amount: {
            value: '2.00',
            currency: 'RUB'
        }
    };
    
    try {
        const payment = await checkout.capturePayment(paymentId, capturePayload, idempotenceKey);
        console.log(payment)
    } catch (error) {
         console.error(error);
    }

    Cancel payment

    import { YooCheckout } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });
    
    const paymentId = '21966b95-000f-50bf-b000-0d78983bb5bc';
    
    const idempotenceKey = '02347fc4-a1f0-49db-807e-f0d67c2ed5a5';
    
    try {
        const payment = await checkout.cancelPayment(paymentId, idempotenceKey);
        console.log(payment)
    } catch (error) {
         console.error(error);
    }

    Get payment list

    import { YooCheckout, IGetPaymentList } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });
    
    const filters: IGetPaymentList = { created_at: { value: '2021-01-27T13:58:02.977Z', mode: 'gte' },  limit: 20 };
    
    try {
        const paymentList = await checkout.getPaymentList(filters);
        console.log(paymentList)
    } catch (error) {
         console.error(error);
    }

    Create refund

    import { YooCheckout, ICreateRefund } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });
    
    const idempotenceKey = '02347fc4-a1f0-49db-807e-f0d67c2ed5a5';
    
    const createRefundPayload: ICreateRefund = {
        payment_id: '27a3852a-000f-5000-8000-102d922df8db',
        amount: {
            value: '1.00',
            currency: 'RUB'
        }
    };
    
    try {
        const refund = await checkout.createRefund(createRefundPayload, idempotenceKey);
        console.log(refund)
    } catch (error) {
         console.error(error);
    }

    Get refund

    import { YooCheckout } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });
    
    const refundId = '21966b95-000f-50bf-b000-0d78983bb5bc';
    
    try {
        const refund = await checkout.getRefund(refundId);
        console.log(refund)
    } catch (error) {
         console.error(error);
    }

    Get refund list

    import { YooCheckout, IGetRefundList } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });
    
    const filters: IGetRefundList = { created_at: { value: '2021-01-27T13:58:02.977Z', mode: 'gte' },  limit: 20 };
    
    try {
        const refundList = await checkout.getRefundList(filters);
        console.log(refundList)
    } catch (error) {
         console.error(error);
    }

    Create receipt

    import { YooCheckout, ICreateReceipt } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });
    
    const idempotenceKey = '02347fc4-a1f0-49db-807e-f0d67c2ed5a5';
    
    const createReceiptPayload: ICreateReceipt = {
        send: true,
        customer: {
            email: 'test@gmail.com'
        },
        settlements: [
            {
                type: 'cashless',
                amount: {
                    value: '2.00',
                    currency: 'RUB'
                }
            }
        ],
        refund_id: '27a387af-0015-5000-8000-137da144ce29',
        type: 'refund',
        items: [
            {
                description: 'test',
                quantity: '2',
                amount: {
                    value: '1.00',
                    currency: 'RUB'
                },
                vat_code: 1,
            }
        ]
    };
    
    try {
        const receipt = await checkout.createReceipt(createReceiptPayload, idempotenceKey);
        console.log(receipt)
    } catch (error) {
         console.error(error);
    }

    Get receipt

    import { YooCheckout } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });
    
    const receiptId = '21966b95-000f-50bf-b000-0d78983bb5bc';
    
    try {
        const receipt = await checkout.getReceipt(receiptId);
        console.log(receipt)
    } catch (error) {
         console.error(error);
    }

    Get receipt list

    import { YooCheckout, IGetReceiptList } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });
    
    const filters: IGetReceiptList = { created_at: { value: '2021-01-27T13:58:02.977Z', mode: 'gte' },  limit: 20 };
    
    try {
        const receiptList = await checkout.getReceiptList(filters);
        console.log(receiptList)
    } catch (error) {
         console.error(error);
    }

    The following functionality works only as part of an affiliate program

    Create webhook

    import { YooCheckout, ICreateWebHook } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey', token: 'your_OAuth_token' });
    
    const idempotenceKey = '02347fc4-a1f0-49db-807e-f0d67c2ed5a5';
    const createWebHookPayload: ICreateWebHook = {
        event: 'payment.canceled',
        url: 'https://test.com/hook'
    };
    
    try {
        const webhook = await checkout.createWebHook(createWebHookPayload, idempotenceKey);
        console.log(webhook)
    } catch (error) {
         console.error(error);
    }

    Get webhook list

    import { YooCheckout } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey', token: 'your_OAuth_token' });
    try {
        const webHookList = await checkout.getWebHookList();
        console.log(webHookList)
    } catch (error) {
         console.error(error);
    }

    Delete webhook

    import { YooCheckout, ICreateWebHook } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey', token: 'your_OAuth_token' });
    
    const webHookId = 'wh-edba6d49-ce3e-4d99-991b-4bb164859dc3';
    
    try {
        await checkout.deleteWebHook(webHookId);
    } catch (error) {
         console.error(error);
    }

    Get shop info

    import { YooCheckout, ICreateWebHook } from '@a2seven/yoo-checkout';
    
    const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey', token: 'your_OAuth_token' });
    
    try {
       const shop = await checkout.getShop();
       console.log(shop)
    } catch (error) {
         console.error(error);
    }

    Running Tests

    To install the development dependencies (run where the package.json is):

    $ npm install

    Run the tests:

    $ npm run test:unit

    Install

    npm i @a2seven/yoo-checkout

    DownloadsWeekly Downloads

    149

    Version

    1.1.2

    License

    MIT

    Unpacked Size

    65.1 kB

    Total Files

    110

    Last publish

    Collaborators

    • nikita-chizhevich
    • a2seven_npm