README

安装

composer require enot-payment/enot

使用

为了工作需要获取

"shopId" - 收银机标识符

"shopSecretKey" - 收银机密钥（在个人控制台中生成，在“收银机”->“集成”部分获得）

"userId" - 用户标识符

"userSecretKey" - 用户密钥 "userSecretKey"（在个人控制台中生成，在“配置文件设置”->“集成”部分获得）

"webhookPaymentKey" - 计算WebHook支付哈希的秘密密钥（收银机额外密钥）

"webhookPayoffKey" - 计算WebHook结算哈希的秘密密钥（用户额外密钥）

初始化

use Enot\Api\Http\EnotFacade;

$facade = new EnotFacade(
        $shopId,
        $shopSecretKey,
        $userId,
        $userSecretKey,
        $webhookPaymentKey,
        $webhookPayoffKey
);

获取可用的支付方法和费率

$response = $facade->getAvailablePaymentTariffs();

✅ 成功响应将返回包含“tariffs”参数的对象 PaymentAvailableTariffsDto，该参数是 PaymentTariffParamsResponseDto 对象的数组，包含以下参数：

必填项

"percent" - 总佣金百分比
"fix" - 固定佣金
"service" - 支付方法代码
"currency" - 货币
"status" - 费率状态（enabled 或 disabled）

可选项

"minSum" - 最小支付金额
"maxSum" - 最大支付金额
"shopPercent" - 从收银机收取的佣金百分比
"userPercent" - 从客户收取的佣金百分比
"serviceLabel" - 支付方法名称

❌ 如果响应失败，将抛出包含错误描述的 PaymentException 类型异常。

创建支付

createInvoice() 方法接受 InvoiceCreateRequestDto 参数。

InvoiceCreateRequestDto 接受以下参数

必填项

"amount" - 发票金额
"orderId" - 您系统中的订单标识符

可选项

"currency" - 支付货币（RUB, USD, EUR, UAH）
"hookUrl" - 发送 webhook 的 URL
"customFields" - 在支付后返回的通知中的字符串，格式为 JSON 字符串
"comment" - 支付目的（支付时显示给客户）
"failUrl" - 支付错误时用户将被重定向的 URL
"successUrl" - 支付成功时用户将被重定向的 URL
"expire" - 发票的生命周期（分钟）
"includeService" - 在账单页面上可用的支付方法
"excludeService" - 在账单页面上不可用的支付方法

use Enot\Api\Dto\Request\Payment\InvoiceCreateRequestDto;

$invoiceCreateRequestDto = new InvoiceCreateRequestDto(
    50.05,
    'orderId',
    'RUB',
    'https://exaple.com',
    '{\"order\": \"74056\"}',
    'comment',
    'https://exaple.com/fail',
    'https://exaple.com/success',
    300.05,
    [
        'card'
    ],
    [
        'qiwi'
    ]
);

$response = $facade->createInvoice($invoiceCreateRequestDto);

✅ 成功响应将返回包含以下参数的对象 InvoiceCreateResponseDto：

必填项

"id" - 我们系统中的操作 ID
"amount" - 发票金额（以卢布计）
"currency" - 支付货币（RUB, USD, EUR, UAH）
"url" - 支付表单的链接
"expired" - 发票到期时间（格式为 "Y-m-d H:i:s"）

❌ 如果响应失败，将抛出包含错误描述的 PaymentException 类型异常。

获取支付信息

getInvoiceInfo() 方法接受 InvoiceInfoRequestDto 参数。

InvoiceInfoRequestDto 接受以下参数

必填项

"invoiceId" - 交易 ID

可选项

"orderId" - 您系统中的唯一支付标识符

use Enot\Api\Dto\Request\Payment\InvoiceInfoRequestDto;

$invoiceInfoRequestDto = new InvoiceInfoRequestDto(
    '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    'orderId'
);

$response = $facade->getInvoiceInfo($invoiceInfoRequestDto);

✅ 成功响应将返回包含以下参数的对象 InvoiceInfoResponseDto：

必填项

"invoiceId" - 我们系统中的操作 ID
"orderId" - 您系统中的操作 ID
"shopId" - 收银机 ID
"status" - 交易状态
"invoiceAmount" - 支付金额
"currency" - 支付货币（RUB, USD, EUR, UAH）
"createdAt" - 发票创建时间
"expiredAt" - 生命周期结束时间

可选项

"credited" - 记入余额的金额
"payService" - 支付方法
"payerDetails" - 付款人详情
"commissionAmount" - 总佣金（以卢布计）
"commissionPercent" - 总佣金百分比
"shopCommissionAmount" - 从收银机收取的佣金金额
"userCommissionAmount" - 向客户收取的佣金金额
"userCommissionPercent" - 向客户收取的佣金百分比
"customField" - 在创建支付时传递的字符串
"paidAt" - 支付时间

❌ 如果响应失败，将抛出包含错误描述的 InvoiceException 类型异常。

检查支付 WebHook 的签名

我们的系统具有支付状态变更通知功能。

您需要添加必要的URL，以便向收银台集成页面发送http通知。

checkPaymentWebhookSignature()方法用于检查传入WebHook的签名，接受参数

必填项

"webhookRequest" - 请求体，json格式
"signature" - 确认有效性的签名（通过请求头中的'x-api-sha256-signature'传递）

获取传入请求数据的示例代码

$webhookRequest = file_get_contents('php://input');
$headerParams = getallheaders();

if(!isset($signature = $headerParams['x-api-sha256-signature'])) {
    throw new Exception();
}

$facade->checkPaymentWebhookSignature($webhookRequest, $signature);

支付传入Webhook请求的示例

{
"invoice_id":"a750dced-0f08-384a-a441-d0a4dba0cae8",
"status":"success",
"amount":"100.00",
"currency":"RUB",
"order_id":"89f2634c-afa9-3b16-bbde-e4a59ee94639",
"custom_fields":{"user":1},
"type":1,
"pay_time":"2023-04-06 15:53:28",
"pay_service":"card",
"payer_details":"553691******1279",
"code": 1,
"credited":"95.50"
}

✅ 签名检查成功时，返回"True"

❌ 签名检查失败时，返回- "False"

获取用户余额

$response = $facade->getUserBalance();

✅ 成功响应将返回包含以下参数的对象UserBalanceResponseDto

必填项

"balance" - 总余额
"activeBalance" - 可用余额
"freezeBalance" - 冻结余额

❌ 失败响应将抛出类型为UserBalanceException的异常，并包含错误描述。

创建提款申请

createPayoff()方法接受CreatePayoffRequestDto。

CreatePayoffRequestDto接受以下参数

必填项

"service" - 提款服务（完整代码）
"walletTo" - 提款卡号/电话/钱包号码
"amount" - 提款金额

可选项

"orderId" - 您系统中的唯一支付标识符
"comment" - 备注
"hookUrl" - 用于发送提款申请通知的webhook URL
"subtract" - 从谁扣除手续费，余额或金额。默认从金额中扣除。

use Enot\Api\Dto\Request\Payoff\CreatePayoffRequestDto;

$createPayoffRequestDto = new CreatePayoffRequestDto(
    'card',
    '1234567890123456'
    100.05,
    'orderId',
    'comment',
    'https://exaple.com',
    1
);

✅ 成功响应将返回包含以下参数的对象CreatePayoffResponseDto

必填项

"payoffId" - 提款ID
"amountWithdrawRub" - 从余额中扣除的金额（以卢布为单位）
"balance" - 扣除提款金额后的余额

❌ 失败响应将抛出类型为PayoffException的异常，并包含错误描述。

获取提款信息

getPayoffInfo()方法接受PayoffInfoRequestDto。

PayoffInfoRequestDto接受以下参数

必填项

"id" - 提款ID

可选项

"orderId" - 您系统中的唯一支付标识符

use Enot\Api\Dto\Request\Payoff\PayoffInfoRequestDto;

$payoffInfoRequestDto = new PayoffInfoRequestDto(
    '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    'orderId'
);

✅ 成功响应将返回包含以下参数的对象PayoffInfoResponseDto

必填项

"payoffId" - 提款ID
"status" - 提款状态
"orderId" - 您系统中的唯一支付标识符
"service" - 提款服务（完整代码）
"type" - 提款类型
"subtract" - 从谁扣除手续费，余额或金额
"amount" - 提款金额（以卢布为单位）
"amountWithdrawRub" - 从余额中扣除的金额（以卢布为单位）
"commissionRub" - 手续费（以卢布为单位）
"receiveCurrency" - 提款货币
"amountReceive" - 提款金额（以货币为单位）
"createdAt" - 提款创建时间

可选项

"wallet" - 提款卡号/电话/钱包号码
"comment" - 创建提款时指定的备注
"paidAt" - 提款时间
"errorMessage" - 拒绝原因

❌ 失败响应将抛出类型为PayoffException的异常，并包含错误描述。

检查提款WebHook签名

我们的系统具有关于提款状态变更的通知功能。

您需要在批量提款页面上添加必要的URL，以便发送通知。您可以将链接添加到您的任何网站上。

仅向使用API创建的交易发送通知。如果提款是通过个人控制台请求的，则不会发送通知。状态变更后，您将通过您的链接收到通知。

checkPayoffWebhookSignature()方法用于检查传入WebHook的签名，接受参数

必填项

"webhookRequest" - 请求体，json格式
"signature" - 确认有效性的签名（通过请求头中的'x-api-sha256-signature'传递）