### Install PayEase SDK

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Use Composer to install the package into your project.

```shell
$ composer require hedeqiang/payease -vvv
```

--------------------------------

### Installation and Usage

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Instructions on how to install the SDK using Composer and basic usage for initializing the Pay class.

```APIDOC
## Installing

```shell
$ composer require hedeqiang/payease -vvv
```

## Usage

```php
require __DIR__ .'/vendor/autoload.php';
use Hedeqiang\PayEase\Pay;
$app = new Pay([
    'privateKey' => '/parth/client.pfx',
    'publicKey'  => 'path/test.cer',  // 注意： 此公钥为首信易的公钥、并非上传到商户后台的公钥！！！
    'merchantId' => '890000593',
    'password'   => '123456',
]);
```
```

--------------------------------

### Order Response Example

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Example JSON response received after placing an order.

```json
{
    "redirectUrl": "https://payment.5upay.com/receipt/index/db50e5bac76e40b18cbd5da1ce238cca",
    "merchantId": "890000593",
    "requestId": "1653644302",
    "hmac": "F9apHKePPFzC3Xp9Dxafd8m0/NhDLuxlwCqxTZtDBqtFyoA31pRlsulOxYDGVXI0o73XUUtzfLpu+ghGo1CQM+r6wqp/vE0UCv7CYWlay5de0A7MmtKpavgDengt7mvht9RL5cmvZS7RkYEsEde84n21LNxscjlRM2kl8AGUupqzDh0nbwgkzfOBeGKPjTvklqFgrjdPkgBhxDP9QZxcQvnD4c4vML27sjqA2FaUxxl2qj9SGPFkzGQ/slX9zMfWbDRWnmvtDF9j0/Uq/LshaBlAa34zUcWumed357Tcmwqe6poIQtThn5clBtBbH9c5ZQBZYkCis5nes+MZVKr5Gw==",
    "paymentOrderId": "db50e5bac76e40b18cbd5da1ce238cca",
    "status": "REDIRECT"
}
```

--------------------------------

### Callback Response Examples

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Examples of data returned by the callback handler for successful and cancelled payments.

```php
 array (
  'cardType' => 'CREDIT_CARD',
  'clearingOrg' => 'UNION_PAY',
  'completeDateTime' => '2022-05-27 16:31:31',
  'merchantId' => '890000593',
  'orderAmount' => '1',
  'orderCurrency' => 'CNY',
  'paymentModeAlias' => 'WAP',
  'realBankRequestNumber' => '4itnydmtesuN',
  'realBankSerialNumber' => '862205271630378302598',
  'remark' => '备注',
  'requestId' => '1653640218',
  'serialNumber' => 'c7117326f3ab4d4c94bf5755c38e1793',
  'status' => 'SUCCESS',
  'totalRefundAmount' => '0',
  'totalRefundCount' => '0',
) 
```

```php
array (
  'completeDateTime' => '2022-05-27 16:38:34',
  'merchantId' => '890000593',
  'orderAmount' => '1',
  'orderCurrency' => 'CNY',
  'remark' => '备注',
  'requestId' => '1653640093',
  'serialNumber' => '32d0e64a43df4561973e47733ffd9f02',
  'status' => 'CANCEL',
  'totalRefundAmount' => '0',
  'totalRefundCount' => '0',
)
```

--------------------------------

### Hyperf Service Usage

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Interact with the PayEase service in Hyperf using the container instance. This example shows how to make requests and handle notifications.

```php
<?php

use Hedeqiang\PayEase\Pay;
use Hyperf\Utils\ApplicationContext;

// 请求
response = ApplicationContext::getContainer()->get(Pay::class)->request($uri,$parmas);

// 回调
$response = ApplicationContext::getContainer()->get(Pay::class)->handleNotify();
```

--------------------------------

### Initialize PayEase Client

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Configure the Pay instance with your merchant credentials and file paths for keys.

```php
require __DIR__ .'/vendor/autoload.php';
use Hedeqiang\\
```

--------------------------------

### Initialize Pay Client

Source: https://context7.com/hedeqiang/payease/llms.txt

Create a Pay client instance for initiating payment requests. Requires merchant private key, PayEase public key, merchant ID, and private key password.

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Hedeqiang\PayEase\Pay;

// 创建 Pay 客户端实例
$app = new Pay([
    'privateKey' => '/path/to/client.pfx',    // 商户私钥文件路径 (PFX 格式)
    'publicKey'  => '/path/to/server.cer',    // 首信易公钥文件路径
    'merchantId' => '890000593',               // 商户 ID
    'password'   => '123456',                  // 私钥密码
]);

// 现在可以使用 $app 发起各种支付请求

```

--------------------------------

### Pay Client Initialization

Source: https://context7.com/hedeqiang/payease/llms.txt

Initialize the Pay client with your merchant credentials and key file paths to interact with the PayEase API.

```APIDOC
## Initialize Pay Client

### Description
Create a Pay client instance to initiate payment requests. Requires configuration of merchant private key file path, PayEase public key file path, merchant ID, and private key password.

### Method
```php
new Pay(array $config)
```

### Parameters
#### Request Body
- **privateKey** (string) - Required - Path to the merchant's private key file (PFX format).
- **publicKey** (string) - Required - Path to the PayEase public key file.
- **merchantId** (string) - Required - Your merchant ID.
- **password** (string) - Required - Password for the private key.

### Request Example
```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Hedeqiang\PayEase\Pay;

// Create Pay client instance
$app = new Pay([
    'privateKey' => '/path/to/client.pfx',    // Merchant private key file path (PFX format)
    'publicKey'  => '/path/to/server.cer',    // PayEase public key file path
    'merchantId' => '890000593',               // Merchant ID
    'password'   => '123456',                  // Private key password
]);

// Now you can use $app to make various payment requests
```
```

--------------------------------

### Sub-merchant Onboarding Request

Source: https://context7.com/hedeqiang/payease/llms.txt

Submit a sub-merchant onboarding application using the service provider declaration interface. Requires valid certificate paths and merchant information.

```php
<?php

use Hedeqiang\PayEase\Pay;

$app = new Pay([
    'privateKey' => '/path/to/client.pfx',
    'publicKey'  => '/path/to/server.cer',
    'merchantId' => '890000593',
    'password'   => '123456',
]);

$uri = 'serviceprovider/declaration/declare';

$params = [
    'requestId'           => time(),
    'operationType'       => 'CREATE',                                    // 操作类型：CREATE/UPDATE
    'notifyUrl'           => 'https://example.com/merchant/notify',       // 入网结果回调地址
    'extendedParameters'  => 'autoReview:FALSE,sendActiveEmail:TRUE',     // 扩展参数
    'baseInfo'            => [
        'signedType'              => 'BY_SPLIT_BILL',         // 签约类型
        'signedName'              => '测试商户',               // 签约名称
        'registerRole'            => 'NATURAL_PERSON',        // 注册角色：自然人
        'signedShorthand'         => '测试',                   // 签约简称
        'businessAddressProvince' => '110000',                // 经营地址省
        'businessAddressCity'     => '110100',                // 经营地址市
        'businessAddressArea'     => '110106',                // 经营地址区
        'businessAddress'         => '北京市朝阳区xxx街道',    // 详细经营地址
        'contactName'             => '张三',                   // 联系人姓名
        'contactEmail'            => 'contact@example.com',   // 联系人邮箱
        'contactPhone'            => '13800138000',           // 联系人电话
        'desireAuth'              => 'DESIRE_MOBILEINFO',     // 开户意愿核实类型
    ],
    'bankCardInfo'        => [
        'accountName'      => '张三',                         // 开户名称
        'bankCardNo'       => '6217000000001234567',          // 银行卡号
        'provinceCode'     => '130000',                       // 开户行省份
        'cityCode'         => '130100',                       // 开户行城市
        'liquidationType'  => 'SETTLE',                       // 清算方式
        'accountType'      => 'PRIVATE',                      // 结算银行卡属性：对私
        'withdrawRateType' => 'SINGLE',                       // 提现费率类型
    ],
    'desireAuthInfo'      => [
        'legalPersonName'    => '张三',                       // 法人姓名
        'legalPersonIdNo'    => '110101199001011234',         // 法人身份证号
        'legalPersonPhoneNo' => '13800138000',                // 法人手机号
    ],
    'certificateInfo'     => [
        'legalPersonName'         => '张三',
        'profession'              => '1',                     // 法人职业
        'legalPersonIdType'       => 'IDCARD',               // 法人证件类型
        'legalPersonIdNo'         => '110101199001011234',
        'legalIdCardProsPath'     => '/serviceprovider/TestData/idcard_front.jpg',  // 身份证人像面
        'legalIdCardConsPath'     => '/serviceprovider/TestData/idcard_back.jpg',   // 身份证国徽面
        'holdingIdCardPath'       => '/serviceprovider/TestData/holding_idcard.jpg', // 手持证件照
        'legalPersonBankCardPath' => '/serviceprovider/TestData/bankcard.jpg',       // 银行卡影印件
        'legalPersonPhone'        => '13800138000'
    ],
    'certificateContacts' => [
        [
            'name'   => '张三',
            'idType' => 'IDCARD',
            'idNo'   => '110101199001011234',
        ]
    ],
    'contractInfo'        => [
        'contractType' => 'ELECTRON',                         // 合同类型：电子合同
    ],
];

$result = $app->request($uri, $params);

// 返回入网申请结果
```

--------------------------------

### Publish Hyperf Configuration

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Execute this command to publish the PayEase configuration for the Hyperf framework. This makes the configuration available for modification.

```bash
php bin/hyperf.php vendor:publish hedeqiang/payease
```

--------------------------------

### Hyperf 框架集成示例

Source: https://context7.com/hedeqiang/payease/llms.txt

在 Hyperf 框架中，通过依赖注入容器获取 Pay 实例来使用 SDK。需要先发布配置文件并配置 .env 文件。

```php
<?php

// 1. 发布配置文件
// php bin/hyperf.php vendor:publish hedeqiang/payease

// 2. 配置 .env 文件
// PAYEASE_PRIVATIVE_KEY=/path/to/client.pfx
// PAYEASE_PUBLIC_KEY=/path/to/server.cer
// PAYEASE_MERCHAN_ID=890000593
// PAYEASE_PASSWORD=123456

// 3. 在控制器中使用
namespace App\Controller;

use Hedeqiang\PayEase\Pay;
use Hyperf\Utils\ApplicationContext;

class PaymentController
{
    public function order()
    {
        $uri = 'onlinePay/order';
        $params = [
            "callbackUrl"    => "https://example.com/callback",
            "clientIp"       => "127.0.0.1",
            "notifyUrl"      => "https://example.com/notify",
            "orderAmount"    => "100",
            "orderCurrency"  => "CNY",
            "payer"          => new \stdClass(),
            "productDetails" => [
                ["amount" => "100", "name" => "商品名称", "quantity" => "1", "receiver" => "收货人"]
            ],
            "remark"    => "订单备注",
            "requestId" => uniqid(),
            "timeout"   => "30"
        ];

        // 从容器获取 Pay 实例
        $response = ApplicationContext::getContainer()->get(Pay::class)->request($uri, $params);

        return $response;
    }

    public function notify()
    {
        // 处理回调通知
        $response = ApplicationContext::getContainer()->get(Pay::class)->handleNotify();

        if ($response && $response['status'] === 'SUCCESS') {
            // 处理支付成功逻辑
        }

        return 'SUCCESS';
    }
}
```

--------------------------------

### Secondary Merchant Onboarding

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Use this PHP code to onboard a secondary merchant with PayEase. Ensure all required parameters are correctly populated.

```php
$uri = 'serviceprovider/declaration/declare';

$params = [
    'requestId'           => time(),
    'operationType'       => 'CREATE',
    'notifyUrl'           => 'https://www.5upay.com/callback.action?test=test',
    'extendedParameters'  => 'autoReview:FALSE,sendActiveEmail:TRUE',
    'baseInfo'            => [
        'signedType'              => 'BY_SPLIT_BILL',
        'signedName'              => 'xxx',  //签约名
        'registerRole'            => 'NATURAL_PERSON',
        'signedShorthand'         => 'xxx',
        'businessAddressProvince' => '110000', //经营地址省
        'businessAddressCity'     => '110100', //经营地址市
        'businessAddressArea'     => '110106', // 经营地址区
        'businessAddress'         => '北京市', //经营地址
        'contactName'             => 'xxx', // 联系人姓名
        'contactEmail'            => 'xxx@163.com', //联系人邮箱
        'contactPhone'            => 'xxx',// 联系人电话
        //'businessClassification'  => 'INTERNAL_TESTING_01', //业务分类
        'desireAuth'              => 'DESIRE_MOBILEINFO', //开户意愿核实类型

    ],
    'bankCardInfo'        => [
        'accountName'      => 'xxx', // 开户名称
        'bankCardNo'       => 'xxx',
        'provinceCode'     => '130000',
        'cityCode'         => '130100',
        'liquidationType'  => 'SETTLE', //清算方式
        'accountType'      => 'PRIVATE', //结算银行卡属性
        'withdrawRateType' => 'SINGLE',
    ],
    'desireAuthInfo'      => [
        'legalPersonName'    => 'xxx', //法人姓名
        'legalPersonIdNo'    => 'xxx', // 法人身份证号
        'legalPersonPhoneNo' => 'xxx', // 法人手机号
    ],
    'certificateInfo'     => [
        'legalPersonName'         => 'xxx',
        'profession'              => '1',// 法人职业
        'legalPersonIdType'       => 'IDCARD',
        'legalPersonIdNo'         => 'xxx',
        'legalIdCardProsPath'     => '/serviceprovider/TestData/111.jpg', //法人证件人像面路径
        'legalIdCardConsPath'     => '/serviceprovider/TestData/111.jpg', //法人证件国徽面路径
        'holdingIdCardPath'       => '/serviceprovider/TestData/111.jpg', //法人手持证件照
        'legalPersonBankCardPath' => '/serviceprovider/TestData/111.jpg', //法人银行卡图影印件路径
        'legalPersonPhone'        => 'xxx'
    ],
    'certificateContacts' => [
        [
            'name'   => 'xxx',
            'idType' => 'IDCARD',
            'idNo'   => 'xxx',
        ]
    ],
    'contractInfo'        => [
//                'receiverAddress' => 'c',
//                'receiverName'    => 'xxx',
//                'receiverPhone'   => 'xxx',
        'contractType'    => 'ELECTRON',
    ],
//            'paymentProfiles'    => [
//                [
//                    'paymentMode' => 'B2C',
//                    'feeType'     => 'SINGLE',
//                ]
//
//            ],
//

];

return $app->request($uri, $params);
```

--------------------------------

### Publish Laravel Configuration

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Use these Artisan commands to publish the PayEase configuration file for Laravel. This makes the configuration easily accessible.

```bash
php artisan vendor:publish --tag=payease
or 
php artisan vendor:publish --provider="Hedeqiang\PayEase\ServiceProvider"
```

--------------------------------

### Yii2 框架集成示例

Source: https://context7.com/hedeqiang/payease/llms.txt

在 Yii2 框架中，通过配置应用组件来集成 SDK。需要在 config/main.php 中进行组件配置，并在控制器中使用。

```php
<?php

// 1. 在 config/main.php 中配置组件
return [
    'components' => [
        'pay' => [
            'class' => 'Hedeqiang\PayEase\YiiPay',
            'options' => [
                'privateKey' => '/path/to/client.pfx',
                'publicKey'  => '/path/to/server.cer',
                'merchantId' => '890000593',
                'password'   => '123456',
            ],
        ],
    ],
];

// 2. 在控制器中使用
namespace app\controllers;

use Yii;
use yii\web\Controller;
use yii\web\Response;

class PaymentController extends Controller
{
    public function actionOrder()
    {
        Yii::$app->response->format = Response::FORMAT_JSON;

        $uri = 'onlinePay/order';
        $params = [
            "callbackUrl"    => Yii::$app->urlManager->createAbsoluteUrl(['payment/callback']),
            "clientIp"       => Yii::$app->request->userIP,
            "notifyUrl"      => Yii::$app->urlManager->createAbsoluteUrl(['payment/notify']),
            "orderAmount"    => "100",
            "orderCurrency"  => "CNY",
            "payer"          => new \stdClass(),
            "productDetails" => [
                ["amount" => "100", "name" => "商品名称", "quantity" => "1", "receiver" => "收货人"]
            ],
            "remark"    => "订单备注",
            "requestId" => uniqid(),
            "timeout"   => "30"
        ];

        // 发起支付请求
        $result = Yii::$app->pay->getPay()->request($uri, $params);

        return $result;
    }

    public function actionNotify()
    {
        // 处理回调通知
        $result = Yii::$app->pay->getPay()->handleNotify();

        if ($result && $result['status'] === 'SUCCESS') {
            // 更新订单状态
        }

        return 'SUCCESS';
    }
}
```

--------------------------------

### Laravel .env Configuration

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Add these variables to your Laravel .env file to configure PayEase credentials. Ensure keys and merchant ID are kept secure.

```dotenv
PAYEASE_PRIVATIVE_KEY=
PAYEASE_PUBLIC_KEY=
PAYEASE_MERCHAN_ID=
PAYEASE_PASSWORD=
```

--------------------------------

### General API Request using request()

Source: https://context7.com/hedeqiang/payease/llms.txt

Use the generic request() method to call various PayEase API interfaces. It automatically handles parameter signing, AES encryption, RSA key exchange, and response decryption.

```php
<?php

use Hedeqiang\PayEase\Pay;

$app = new Pay([
    'privateKey' => '/path/to/client.pfx',
    'publicKey'  => '/path/to/server.cer',
    'merchantId' => '890000593',
    'password'   => '123456',
]);

// 定义 API 路径和请求参数
$uri = 'onlinePay/order';
$params = [
    "callbackUrl"    => "https://example.com/callback",
    "clientIp"       => "10.101.10.10",
    "notifyUrl"      => "https://example.com/notify",
    "orderAmount"    => "100",
    "orderCurrency"  => "CNY",
    "payer"          => new \stdClass(),
    "productDetails" => [
        [
            "amount"      => "100",
            "description" => "黑色64G",
            "name"        => "IPHONE6",
            "quantity"    => "1",
            "receiver"    => "张三"
        ]
    ],
    "remark"    => "订单备注",
    "requestId" => time(),
    "timeout"   => "10"
];

// 发起请求
$result = $app->request($uri, $params);

// 返回示例
// [
//     "redirectUrl" => "https://payment.5upay.com/receipt/index/db50e5bac76e40b18cbd5da1ce238cca",
//     "merchantId" => "890000593",
//     "requestId" => "1653644302",
//     "hmac" => "F9apHKePPFzC3Xp9Dxafd8m0/NhDLuxlwCqxTZtDBqtFyoA31pRlsulOxYDGVXI0...",
//     "paymentOrderId" => "db50e5bac76e40b18cbd5da1ce238cca",
//     "status" => "REDIRECT"
// ]

```

--------------------------------

### Laravel Framework Integration

Source: https://context7.com/hedeqiang/payease/llms.txt

Integrate PayEase into Laravel using service providers and Facades. Ensure configuration is set in the .env file before usage.

```php
<?php

// 1. 发布配置文件
// php artisan vendor:publish --tag=payease

// 2. 配置 .env 文件
// PAYEASE_PRIVATIVE_KEY=/path/to/client.pfx
// PAYEASE_PUBLIC_KEY=/path/to/server.cer
// PAYEASE_MERCHAN_ID=890000593
// PAYEASE_PASSWORD=123456

// 3. 使用服务名访问
namespace App\Http\Controllers;

class PaymentController extends Controller
{
    public function order()
    {
        $uri = 'onlinePay/order';
        $params = [
            "callbackUrl"    => route('payment.callback'),
            "clientIp"       => request()->ip(),
            "notifyUrl"      => route('payment.notify'),
            "orderAmount"    => "100",
            "orderCurrency"  => "CNY",
            "payer"          => new \stdClass(),
            "productDetails" => [
                ["amount" => "100", "name" => "商品名称", "quantity" => "1", "receiver" => "收货人"]
            ],
            "remark"    => "订单备注",
            "requestId" => uniqid(),
            "timeout"   => "30"
        ];

        // 方式一：使用服务名访问
        return app('pay')->request($uri, $params);
    }
}

// 4. 使用 Facade 门面
use Hedeqiang\PayEase\Facades\Pay;

class PaymentController extends Controller
{
    public function order()
    {
        $uri = 'onlinePay/order';
        $params = [...];

        return Pay::pay()->request($uri, $params);
    }

    public function notify(Request $request)
    {
        $result = Pay::pay()->handleNotify();

        if ($result && $result['status'] === 'SUCCESS') {
            // 处理支付成功逻辑
        }

        return 'SUCCESS';
    }
}
```

--------------------------------

### Yii2 Usage

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Demonstrates how to make requests and handle notifications using the configured PayEase component in Yii2. Ensure the response format is set to JSON.

```php
Yii::$app->response->format = Response::FORMAT_JSON;

// 请求
$results = Yii::$app->pay->getPay()->request($uri,$params);
// 回调
$results = Yii::$app->pay->getPay()->handleNotify();
```

--------------------------------

### Place an Order

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Submit an order request to the PayEase API using the request method.

```php
$uri = 'onlinePay/order';

$params = [
    "callbackUrl"    => "https://demo.5upay.com/sdk/callback",
    "clientIp"       => "10.101.10.10",
    "hmac"           => null,
    "notifyUrl"      => "https://demo.5upay.com/sdk/onlinepay/notify",
    "orderAmount"    => "1",
    "orderCurrency"  => "CNY",
    "payer"          => new \stdClass(),
//    "payer" => [
//        "bankCardNum" =>"6217000xxxxx",
//        "email" =>"laravel_code@163.com",
//        "idNum" =>"xxxx",
//        "idType" =>"IDCARD",
//        "name" =>"xxx",
//        "phoneNum" =>"xxx"
//    ],
    // "paymentModeCode" =>"BANK_CARD-B2C-ICBC-P2P",
    "productDetails" => [
        [
            "amount"      => "1",
            "description" => "黑色64G",
            "name"        => "IPHONE6",
            "quantity"    => "100",
            "receiver"    => "张三"
        ]
    ],
    "remark"         => "备注",
    "requestId"      => time(),
    "timeout"        => "10"
];
$app->request($uri,$params)
```

--------------------------------

### General API Request

Source: https://context7.com/hedeqiang/payease/llms.txt

Use the `request()` method for general API calls, which handles signing, encryption, and decryption automatically.

```APIDOC
## request() - Make API Request

### Description
A general request method used to call various PayEase API interfaces. This method automatically handles parameter signing, AES encryption, RSA key exchange, and response decryption, returning decrypted array data.

### Method
```php
request(string $uri, array $params)
```

### Parameters
#### Path Parameters
- **uri** (string) - Required - The API endpoint path.

#### Request Body
- **params** (array) - Required - An associative array of parameters for the API request.

### Request Example
```php
<?php

use Hedeqiang\PayEase\Pay;

$app = new Pay([
    'privateKey' => '/path/to/client.pfx',
    'publicKey'  => '/path/to/server.cer',
    'merchantId' => '890000593',
    'password'   => '123456',
]);

// Define API path and request parameters
$uri = 'onlinePay/order';
$params = [
    "callbackUrl"    => "https://example.com/callback",
    "clientIp"       => "10.101.10.10",
    "notifyUrl"      => "https://example.com/notify",
    "orderAmount"    => "100",
    "orderCurrency"  => "CNY",
    "payer"          => new \stdClass(),
    "productDetails" => [
        [
            "amount"      => "100",
            "description" => "黑色64G",
            "name"        => "IPHONE6",
            "quantity"    => "1",
            "receiver"    => "张三"
        ]
    ],
    "remark"    => "订单备注",
    "requestId" => time(),
    "timeout"   => "10"
];

// Make the request
$result = $app->request($uri, $params);

// Response Example
// [
//     "redirectUrl" => "https://payment.5upay.com/receipt/index/db50e5bac76e40b18cbd5da1ce238cca",
//     "merchantId" => "890000593",
//     "requestId" => "1653644302",
//     "hmac" => "F9apHKePPFzC3Xp9Dxafd8m0/NhDLuxlwCqxTZtDBqtFyoA31pRlsulOxYDGVXI0...",
//     "paymentOrderId" => "db50e5bac76e40b18cbd5da1ce238cca",
//     "status" => "REDIRECT"
// ]
```
```

--------------------------------

### Laravel Facade Usage

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Utilize the PayEase Facade in Laravel for convenient access to its methods. This provides a more fluent interface for common operations.

```php
use Hedeqiang\PayEase\Facades\Pay;

public function index()
{
   return Pay::pay()->request($uri,$params)
}

public function notify(Request $request)
{
   $result = Pay::pay()->handleNotify();
}
```

--------------------------------

### POST /onlinePay/order - Create Order

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Endpoint for creating a new order. This initiates the payment process and returns a redirect URL for the payment gateway.

```APIDOC
## POST /onlinePay/order

### Description
Creates a new order for payment processing. The response includes a `redirectUrl` that the client should use to initiate the payment.

### Method
POST

### Endpoint
`onlinePay/order`

### Parameters
#### Request Body
- **callbackUrl** (string) - Required - The URL to redirect to after the payment is completed.
- **clientIp** (string) - Required - The IP address of the client making the payment.
- **notifyUrl** (string) - Required - The URL to receive asynchronous payment notifications.
- **orderAmount** (string) - Required - The total amount of the order.
- **orderCurrency** (string) - Required - The currency of the order (e.g., CNY).
- **payer** (object) - Required - Information about the payer.
  - **bankCardNum** (string) - Optional - Payer's bank card number.
  - **email** (string) - Optional - Payer's email address.
  - **idNum** (string) - Optional - Payer's ID number.
  - **idType** (string) - Optional - Payer's ID type (e.g., IDCARD).
  - **name** (string) - Optional - Payer's name.
  - **phoneNum** (string) - Optional - Payer's phone number.
- **paymentModeCode** (string) - Optional - The specific payment mode to use.
- **productDetails** (array) - Required - An array of product details.
  - **amount** (string) - Required - The amount for this product.
  - **description** (string) - Required - Description of the product.
  - **name** (string) - Required - Name of the product.
  - **quantity** (string) - Required - Quantity of the product.
  - **receiver** (string) - Required - Name of the product receiver.
- **remark** (string) - Optional - Any remarks for the order.
- **requestId** (string) - Required - A unique identifier for the request.
- **timeout** (string) - Optional - The timeout for the payment.

### Request Example
```json
{
    "callbackUrl": "https://demo.5upay.com/sdk/callback",
    "clientIp": "10.101.10.10",
    "notifyUrl": "https://demo.5upay.com/sdk/onlinepay/notify",
    "orderAmount": "1",
    "orderCurrency": "CNY",
    "payer": {},
    "productDetails": [
        {
            "amount": "1",
            "description": "黑色64G",
            "name": "IPHONE6",
            "quantity": "100",
            "receiver": "张三"
        }
    ],
    "remark": "备注",
    "requestId": "1653644302",
    "timeout": "10"
}
```

### Response
#### Success Response (200)
- **redirectUrl** (string) - The URL to redirect the user to for payment.
- **merchantId** (string) - The merchant ID.
- **requestId** (string) - The request ID.
- **hmac** (string) - The HMAC signature for the response.
- **paymentOrderId** (string) - The unique ID of the payment order.
- **status** (string) - The status of the order (e.g., REDIRECT).

#### Response Example
```json
{
    "redirectUrl": "https://payment.5upay.com/receipt/index/db50e5bac76e40b18cbd5da1ce238cca",
    "merchantId": "890000593",
    "requestId": "1653644302",
    "hmac": "F9apHKePPFzC3Xp9Dxafd8m0/NhDLuxlwCqxTZtDBqtFyoA31pRlsulOxYDGVXI0o73XUUtzfLpu+ghGo1CQM+r6wqp/vE0UCv7CYWlay5de0A7MmtKpavgDengt7mvht9RL5cmvZS7RkYEsEde84n21LNxscjlRM2kl8AGUupqzDh0nbwgkzfOBeGKPjTvklqFgrjdPkgBhxDP9QZxcQvnD4c4vML27sjqA2FaUxxl2qj9SGPFkzGQ/slX9zMfWbDRWnmvtDF9j0/Uq/LshaBlAa34zUcWumed357Tcmwqe6poIQtThn5clBtBbH9c5ZQBZYkCis5nes+MZVKr5Gw==",
    "paymentOrderId": "db50e5bac76e40b18cbd5da1ce238cca",
    "status": "REDIRECT"
}
```
```

--------------------------------

### Handle Callback Notification

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Process incoming payment notifications from the gateway.

```php
$result = $app->handleNotify();
// TODO

return 'SUCCESS' ; // retuen 'Fail';
```

--------------------------------

### Yii2 Configuration

Source: https://github.com/hedeqiang/payease/blob/main/README.md

Configure the PayEase component in your Yii2 application's main configuration file. This involves setting the class and necessary options.

```php
'components' => [
    // ...
    'pay' => [
        'class' => 'Hedeqiang\PayEase\YiiPay',
        'options' => [
            'privateKey' => '/private.pfx',
            'publicKey' => '//server.cer',
            'merchantId' => '890000593',
            'password' => '123456',
        ],
    ],
    // ...
]
```

--------------------------------

### Online Payment Order

Source: https://context7.com/hedeqiang/payease/llms.txt

Initiate an online payment order. Users will be redirected to the PayEase payment page via the returned `redirectUrl`.

```APIDOC
## Immediately Place Order (Online Payment)

### Description
Initiate an online payment order request. Users can complete the payment by accessing the PayEase cashier page through the returned `redirectUrl`. Supports passing parameters such as payer information, product details, and order amount.

### Method
```php
request(string $uri, array $params)
```

### Endpoint
`onlinePay/order`

### Parameters
#### Request Body
- **callbackUrl** (string) - Required - The URL to redirect to after payment completion.
- **clientIp** (string) - Required - The client's IP address.
- **notifyUrl** (string) - Required - The asynchronous notification URL.
- **orderAmount** (string) - Required - The order amount (in cents).
- **orderCurrency** (string) - Required - The currency code (e.g., CNY).
- **payer** (object|array) - Optional - Payer information. Can be an empty object or contain details like `bankCardNum`, `email`, `idNum`, `idType`, `name`, `phoneNum`.
- **paymentModeCode** (string) - Optional - Specifies the payment method (e.g., 'BANK_CARD-B2C-ICBC-P2P').
- **productDetails** (array) - Required - An array of product details, each containing `amount`, `description`, `name`, `quantity`, and `receiver`.
- **remark** (string) - Optional - Order remarks.
- **requestId** (string) - Required - A unique request ID.
- **timeout** (string) - Optional - Timeout duration in minutes.

### Request Example
```php
<?php

use Hedeqiang\PayEase\Pay;

$app = new Pay([
    'privateKey' => '/path/to/client.pfx',
    'publicKey'  => '/path/to/server.cer',
    'merchantId' => '890000593',
    'password'   => '123456',
]);

$uri = 'onlinePay/order';

$params = [
    "callbackUrl"    => "https://example.com/callback",      // Payment completion callback URL
    "clientIp"       => "10.101.10.10",                       // Client IP address
    "notifyUrl"      => "https://example.com/notify",         // Asynchronous notification URL
    "orderAmount"    => "1",                                   // Order amount (in cents)
    "orderCurrency"  => "CNY",                                // Currency
    "payer"          => new \stdClass(),                      // Payer information (optional)
    // If you need to pass payer details:
    // "payer" => [
    //     "bankCardNum" => "6217000xxxxx",
    //     "email" => "user@example.com",
    //     "idNum" => "110101199001011234",
    //     "idType" => "IDCARD",
    //     "name" => "张三",
    //     "phoneNum" => "13800138000"
    // ],
    // "paymentModeCode" => "BANK_CARD-B2C-ICBC-P2P",        // Specify payment method (optional)
    "productDetails" => [
        [
            "amount"      => "1",
            "description" => "黑色64G",
            "name"        => "IPHONE6",
            "quantity"    => "100",
            "receiver"    => "张三"
        ]
    ],
    "remark"    => "备注信息",
    "requestId" => time(),                                     // Unique request ID
    "timeout"   => "10"                                        // Timeout duration (minutes)
];

$result = $app->request($uri, $params);

// Response Result
// [
//     "redirectUrl" => "https://payment.5upay.com/receipt/index/db50e5bac76e40b18cbd5da1ce238cca",
//     "merchantId" => "890000593",
//     "requestId" => "1653644302",
//     "hmac" => "F9apHKePPFzC3Xp9Dxafd8m0/NhDLuxlwCqxTZtDBqtFyoA31pRlsulOxYDGVXI0...",
//     "paymentOrderId" => "db50e5bac76e40b18cbd5da1ce238cca",
//     "status" => "REDIRECT"
// ]

// Redirect the user to the cashier page using redirectUrl
header('Location: ' . $result['redirectUrl']);
```
```

--------------------------------

### Initiate Online Payment Order

Source: https://context7.com/hedeqiang/payease/llms.txt

Initiate an online payment order request. The user is redirected to the PayEase cashier via the returned redirectUrl. Supports passing payer information, product details, and order amount.

```php
<?php

use Hedeqiang\PayEase\Pay;

$app = new Pay([
    'privateKey' => '/path/to/client.pfx',
    'publicKey'  => '/path/to/server.cer',
    'merchantId' => '890000593',
    'password'   => '123456',
]);

$uri = 'onlinePay/order';

$params = [
    "callbackUrl"    => "https://example.com/callback",      // 支付完成后的回跳地址
    "clientIp"       => "10.101.10.10",                       // 客户端 IP
    "notifyUrl"      => "https://example.com/notify",         // 异步通知地址
    "orderAmount"    => "1",                                   // 订单金额（单位：分）
    "orderCurrency"  => "CNY",                                // 币种
    "payer"          => new \stdClass(),                      // 付款人信息（可选）
    // 如需传递付款人详情：
    // "payer" => [
    //     "bankCardNum" => "6217000xxxxx",
    //     "email" => "user@example.com",
    //     "idNum" => "110101199001011234",
    //     "idType" => "IDCARD",
    //     "name" => "张三",
    //     "phoneNum" => "13800138000"
    // ],
    // "paymentModeCode" => "BANK_CARD-B2C-ICBC-P2P",        // 指定支付方式（可选）
    "productDetails" => [
        [
            "amount"      => "1",
            "description" => "黑色64G",
            "name"        => "IPHONE6",
            "quantity"    => "100",
            "receiver"    => "张三"
        ]
    ],
    "remark"    => "备注信息",
    "requestId" => time(),                                     // 唯一请求 ID
    "timeout"   => "10"                                        // 超时时间（分钟）
];

$result = $app->request($uri, $params);

// 返回结果
// [
//     "redirectUrl" => "https://payment.5upay.com/receipt/index/db50e5bac76e40b18cbd5da1ce238cca",
//     "merchantId" => "890000593",
//     "requestId" => "1653644302",
//     "hmac" => "F9apHKePPFzC3Xp9Dxafd8m0/NhDLuxlwCqxTZtDBqtFyoA31pRlsulOxYDGVXI0...",
//     "paymentOrderId" => "db50e5bac76e40b18cbd5da1ce238cca",
//     "status" => "REDIRECT"
// ]

// 使用 redirectUrl 重定向用户到收银台
header('Location: ' . $result['redirectUrl']);

```