@a2seven/yoo-checkout 中文文档教程

Question

Yoo.Checkout API SDK (unofficial)

自述文件 на русском！

Yoo.Checkout - 处理在线支付的通用解决方案。 Yoo.Checkout API 基于 REST 原则构建，适用于真实对象并具有可预测的行为。 使用此 API，您可以发送付款请求、保存重复收费的付款信息（包括自动付款）、退款等。 该 API 使用 HTTP 作为主要协议，这意味着它适合使用任何可以使用 HTTP 库的编程语言（例如 cURL）进行开发。 身份验证使用基本身份验证，因此您可以直接从浏览器发出您的第一个请求。 API 支持 POST 和 GET 请求。 POST 请求使用 JSON 参数，GET 请求使用查询字符串。 无论请求类型如何，API 始终以 JSON 格式返回响应。

Authentication

要对请求进行身份验证，您需要使用 HTTP Basic Auth。 在请求的标题中，您需要将您在 YooKassa 中的商店 ID 作为用户名作为密码传递 - 您的密钥（它必须由短信中的密码生成和激活）

带有身份验证的示例请求

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

Idempotency

API 上下文中 ，幂等性意味着多个请求的处理方式与单个请求相同。 这意味着如果您收到具有相同参数的重复请求，您将在响应中获得原始请求的结果。 此行为有助于避免不需要的事务重复。 例如，如果网络出现问题并且在付款时连接中断，您可以安全地重复请求多次。 GET 请求默认是幂等的，因为它们没有不良后果。 Idempotence-Key 标头（或幂等键）用于确保 POST 请求的幂等性。

使用幂等键的查询示例

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"
      }'

如果您使用相同的数据和相同的键重复请求，API 会将其作为重复请求处理。 如果请求中的数据相同，但幂等键不同，则作为新请求执行。 您可以在 Idempotence-Key 标头中传递该操作唯一的任何值。 我们建议使用 V4 UUID。 YooKassa 在第一次请求后 24 小时内提供幂等性，然后第二次请求将作为新请求处理。

Synchronicity

YooKassa 立即处理收到的请求并返回处理结果（“成功”或“失败”）。 如果无法在 30 秒内给出准确的响应，例如由于收单方的问题，YooKassa 将返回 HTTP 代码 500 并尝试取消操作。 要找出请求的最终结果，请使用相同的数据和相同的幂等密钥重复请求。 建议重复频率为每分钟一次，直到 YooKassa 报告 HTTP 500 以外的响应。

HTTP response codes

如果请求处理成功，API 将返回 HTTP 代码 200 和响应正文。 如果在处理过程中发生错误，API 将返回错误对象和标准 HTTP 代码。

HTTP CODE	ERROR CODE	DESCRIPTION
400	invalidrequest, notsupported	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	toomanyrequests	The limit of requests per time unit has been exceeded. Try reducing the intensity of the requests.
500	internalservererror	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.

示例错误响应主体

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

SDK 错误响应

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

Reference

YooKassa API 页面

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

要安装开发依赖项（在 package.json 所在的位置运行）：

$ npm install

运行测试：

$ npm run test:unit