刘. API SDK( 非官方) 检查
读取 на русском!
刘. 离职 - 网上付款的普遍解决办法。 刘人. 取出API是建立在REST-原理上,与真实对象合作,具有可预见的行为. 使用此API,您可以发送支付请求,为重复收费保存支付信息(并包括自动支付),进行退款以及更多. API使用HTTP作为主要协议,这意味着它适合在任何可以和HTTP库(例如cURL)合作的编程语言中进行开发. 认证使用 Basic Auth, 这样您就可以直接从浏览器中发出第一个请求 . API支持POST并获取请求. POST 请求使用 JSON 参数,获得请求与查询字符串的工作. API总是以JSON格式返回一个响应,无论请求的类型如何.
认证
要认证请求, 您需要使用 HTTP Basic Auth 。 在作为用户名的请求信头中,您需要通过位于YooKassa的商店的ID,作为密码 - 您的秘密密钥( 它必须来自 sms 的密码生成并激活)
带有认证的示例请求
curl https://api.yookassa.ru/v3/payments/{payment_id} \
-u <shopId>:<secretKey>
目 录
在API语境下,"一能"指多个请求的处理方式与单一请求相同. 指如果收到重复请求,使用相同的参数,在回复中会得到原始请求的结果. 这种行为有助于避免交易发生不必要的重复. 例如,如果网络出现问题,且连接在支付时被中断,可以安全地重复请求,只要你想要多次. 请求是默认的,因为它们没有不良后果. 使用Idepotence-Key标题(或"idepotence 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会将其作为重复请求处理. 如果请求中的数据是相同的,而"同能"密钥是不同的,则请求作为新请求执行. 您可以在“ 同上”-“关键”标题中将操作中特有的任何价值传递给您。 我们建议使用V4UUID. YooKassa在第一次请求后提供24小时的自首能力,然后将第二次请求作为新的请求处理.
同步
YooKassa 立即处理收到的请求并返回处理结果("成功"或"失败"). 如果在30秒内无法给出确切的响应,例如由于收购者一方出现问题,柳克萨会返回HTTP代码500并尝试取消操作. 为了找出请求的最终结果,用相同的数据和相同的同源密钥来重复请求. 建议的重复频率为每分钟一次,直到YooKassa报告HTTP 500以外的响应.
HTTP 响应代码
如果请求得到成功处理,API会返回HTTP代码200和响应正文. 如果处理过程中发生出错,API会返回出错对象和标准HTTP代码.
| HTTP 代码 | 错误代码 | 解释 |
|---|---|---|
| 400个 | 无效的请求, 不支持 | 请求不正确 。 这种身份往往是由于违反与API互动的规则而发布的. |
| 401 (中文(简体) ) | 无效的证书( c) | [基本 Auth] 您的 YooKassa 账户ID 或密钥( 认证用户名和密码) 无效 。 [OAuth 2. 无效的 OAuth 令牌: 它无效, 过时, 或已被撤销 。 再次请求代号. |
| 403 (韩语) | 禁用内容 | 密钥或 OAuth 令牌正确, 但缺乏完成交易的权限 . |
| 404 (韩语) | 未发现 | 资源未找到 . |
| 429个 | 请求次数太多 | 每个时间单位的请求限额已超过。 尝试降低请求的强度 . |
| 500个 | 内部( s) | 柳卡萨一侧的技术问题. 处理请求的结果不明. 稍后用相同的同能键重复请求. 建议每隔一分钟重复一次请求,直到YooKassa报告业务处理结果. |
示例错误反应机构
{
"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
}
参考文献
安装
npm install @a2seven/yoo-checkout
开始
import { YooCheckout } from '@a2seven/yoo-checkout'; // OR const { YooCheckout } = require('@a2seven/yoo-checkout');
const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });
文档
创建付款
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);
}
拿到钱
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);
}
扣押付款
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);
}
取消付款
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);
}
获取付款列表
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);
}
创建退款
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);
}
退钱
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);
}
获取退款列表
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);
}
创建收件
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: '[email protected]'
},
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);
}
拿收据来
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);
}
获取收件列表
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);
}
以下功能仅作为下列功能的一部分: 附属程序
创建网点
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);
}
获取 Webhook 列表
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);
}
删除网点
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);
}
获取商店信息
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);
}
运行测试
要安装开发依赖( 运行到软件包所在位置 ) :
$ npm install
运行测试 :
$ npm run test:unit