Yansongda Pay

https://github.com/yansongda/pay
Admin
A unified PHP SDK for integrating multiple payment gateways including Alipay, WeChat Pay, Douyin...
Tokens:57,897
Snippets:534
Trust Score:9.1
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Recommended Business Encapsulation Example

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/pay.md

A complete example showing order creation and manual extraction of the payment URL.

```php
$order = [
    '_native_api' => true,
    'amount' => 100,
    'currency' => 'USD',
    'merchant_order_id' => 'order_20260414_001',
    'payment_method' => [
        'type' => 'wechatpay',
        'wechatpay' => [
            'flow' => 'mobile_web',
        ],
    ],
];

$result = Pay::airwallex()->intent($order);

$payUrl = '';
$type = $result->get('next_action.type', '');

switch ($type) {
    case 'render_qrcode':
        $payUrl = $result->get('next_action.qrcode_url')
            ?? $result->get('next_action.url', '');
        break;
    case 'redirect':
        $payUrl = $result->get('next_action.url', '');
        break;
}

return [
    'pay_url' => $payUrl,
    'raw' => $result,
];
```

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

### Install yansongda/pay via Composer

Source: https://github.com/yansongda/pay/blob/master/README.md

Use this command to install the library in your project.

```shell
composer require yansongda/pay:~3.7.0 -vvv
```

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

### Alipay Integration Example

Source: https://github.com/yansongda/pay/blob/master/README.md

Demonstrates configuring the Alipay gateway and handling web payments, return callbacks, and notify callbacks.

```php
<?php

namespace App\Http\Controllers;

use Yansongda\Pay\Pay;

class AlipayController
{
    protected $config = [
        'alipay' => [
            'default' => [
                // 必填-支付宝分配的 app_id
                'app_id' => '2016082000295641',
                // 必填-应用私钥 字符串或路径
                'app_secret_cert' => '89iZ2iC16H6/6a3YcP+hDZUjiNGQx9cuwi9eJyykvcwhD...',
                // 必填-应用公钥证书 路径
                'app_public_cert_path' => '/Users/yansongda/pay/cert/appCertPublicKey_2016082000295641.crt',
                // 必填-支付宝公钥证书 路径
                'alipay_public_cert_path' => '/Users/yansongda/pay/cert/alipayCertPublicKey_RSA2.crt',
                // 必填-支付宝根证书 路径
                'alipay_root_cert_path' => '/Users/yansongda/pay/cert/alipayRootCert.crt',
                'return_url' => 'https://yansongda.cn/alipay/return',
                'notify_url' => 'https://yansongda.cn/alipay/notify',
                // 选填-第三方应用授权token
                'app_auth_token' => '',
                // 选填-服务商模式下的服务商 id，当 mode 为 Pay::MODE_SERVICE 时使用该参数
                'service_provider_id' => '',
                // 选填-默认为正常模式。可选为： MODE_NORMAL, MODE_SANDBOX, MODE_SERVICE
                'mode' => Pay::MODE_NORMAL,
            ],       
        ],   
        'logger' => [ // optional
            'enable' => false,
            'file' => './logs/alipay.log',
            'level' => 'info', // 建议生产环境等级调整为 info，开发环境为 debug
            'type' => 'single', // optional, 可选 daily.
            'max_file' => 30, // optional, 当 type 为 daily 时有效，默认 30 天
        ],
        'http' => [ // optional
            'timeout' => 5.0,
            'connect_timeout' => 5.0,
            // 更多配置项请参考 [Guzzle](https://guzzle-cn.readthedocs.io/zh_CN/latest/request-options.html)
        ],
    ];

    public function web()
    {
        Pay::config($this->config);
        
        $result = Pay::alipay()->web([
            'out_trade_no' => ''.time(),
            'total_amount' => '0.01',
            'subject' => 'yansongda 测试 - 1',
        ]);
        
        return $result;
    }

    public function returnCallback()
    {
        Pay::config($this->config);
    
        $data = Pay::alipay()->callback(); // 是的，验签就这么简单！

        // 订单号：$data->out_trade_no
        // 支付宝交易号：$data->trade_no
        // 订单总金额：$data->total_amount
    }

    public function notifyCallback()
    {
        Pay::config($this->config);
        
        try{
            $data = Pay::alipay()->callback(); // 是的，验签就这么简单！

            // 请自行对 trade_status 进行判断及其它逻辑进行判断，在支付宝的业务通知中，只有交易通知状态为 TRADE_SUCCESS 或 TRADE_FINISHED 时，支付宝才会认定为买家付款成功。
            // 1、商户需要验证该通知数据中的out_trade_no是否为商户系统中创建的订单号；
            // 2、判断total_amount是否确实为该订单的实际金额（即商户订单创建时的金额）；
            // 3、校验通知中的seller_id（或者seller_email) 是否为out_trade_no这笔单据的对应的操作方（有的时候，一个商户可能有多个seller_id/seller_email）；
            // 4、验证app_id是否为该商户本身。
            // 5、其它业务逻辑情况
        } catch (\Throwable $e) {
            dd($e);
        }

        return Pay::alipay()->success();
    }
}
```

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

### Alipay CN Configuration

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/pay.md

Example configuration for Alipay CN using the qrcode flow.

```php
$order = [
    '_native_api' => true,
    'amount' => 100,
    'currency' => 'USD',
    'merchant_order_id' => 'order_20260414_001',
    'payment_method' => [
        'type' => 'alipaycn',
        'alipaycn' => [
            'flow' => 'qrcode', // 或 mobile_web
        ],
    ],
];
```

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

### WeChat Payment Controller Implementation

Source: https://github.com/yansongda/pay/blob/master/README.md

A complete controller example demonstrating configuration, payment initiation, and callback verification for WeChat Pay.

```php
<?php

namespace App\\\Http\\\Controllers;

use Yansongda\\\Pay\\\Pay;

class WechatController
{
    protected $config = [
        'wechat' => [
            'default' => [
                // 必填-商户号
                'mch_id' => '',
                // 选填-v2商户私钥
                'mch_secret_key_v2' => '',
                // 必填-v3商户秘钥
                'mch_secret_key' => '',
                // 必填-商户私钥 字符串或路径
                'mch_secret_cert' => '',
                // 必填-商户公钥证书路径
                'mch_public_cert_path' => '',
                // 必填
                'notify_url' => 'https://yansongda.cn/wechat/notify',
                // 选填-公众号 的 app_id
                'mp_app_id' => '',
                // 选填-小程序 的 app_id
                'mini_app_id' => '',
                // 选填-app 的 app_id
                'app_id' => '',
                // 选填-服务商模式下，子公众号 的 app_id
                'sub_mp_app_id' => '',
                // 选填-服务商模式下，子 app 的 app_id
                'sub_app_id' => '',
                // 选填-服务商模式下，子小程序 的 app_id
                'sub_mini_app_id' => '',
                // 选填-服务商模式下，子商户id
                'sub_mch_id' => '',
                // 选填-微信平台公钥证书路径, optional，强烈建议 php-fpm 模式下配置此参数
                'wechat_public_cert_path' => [
                    '45F59D4DABF31918AFCEC556D5D2C6E376675D57' => __DIR__.'/Cert/wechatpay_45F***D57.pem',
                ],
                // 选填-默认为正常模式。可选为： MODE_NORMAL, MODE_SERVICE
                'mode' => Pay::MODE_NORMAL,
            ]
        ],
        'logger' => [ // optional
            'enable' => false,
            'file' => './logs/wechat.log',
            'level' => 'info', // 建议生产环境等级调整为 info，开发环境为 debug
            'type' => 'single', // optional, 可选 daily.
            'max_file' => 30, // optional, 当 type 为 daily 时有效，默认 30 天
        ],
        'http' => [ // optional
            'timeout' => 5.0,
            'connect_timeout' => 5.0,
            // 更多配置项请参考 [Guzzle](https://guzzle-cn.readthedocs.io/zh_CN/latest/request-options.html)
        ],
    ];

    public function index()
    {
        Pay::config($this->config);
        
        $order = [
            'out_trade_no' => time().'',
            'description' => 'subject-测试',
            'amount' => [
                 'total' => 1,
            ],
            'payer' => [
                 'openid' => 'onkVf1FjWS5SBxxxxxxxx',
            ],
        ];

        $pay = Pay::wechat()->mp($order);

        // $pay->appId
        // $pay->timeStamp
        // $pay->nonceStr
        // $pay->package
        // $pay->signType
    }

    public function callback()
    {
        Pay::config($this->config);
        
        try{
            $data = Pay::wechat()->callback(); // 是的，验签就这么简单！
        } catch (\\Throwable $e) {
            dd($e);
        }
        
        return Pay::wechat()->success();
    }
}
```

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

### Credit Card Payment Configuration

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/pay.md

Example configuration for processing credit card payments with _native_api enabled.

```php
$order = [
    '_native_api' => true,
    'amount' => 100,
    'currency' => 'USD',
    'merchant_order_id' => 'order_20260414_001',
    'return_url' => 'https://example.com/airwallex/return',
    'payment_method' => [
        'type' => 'card',
        'card' => [
            'number' => '4111111111111111',
            'expiry_month' => '12',
            'expiry_year' => '2030',
            'name' => 'John Doe',
            'cvc' => '123',
        ],
    ],
    'payment_method_options' => [
        'card' => [
            'auto_capture' => true,
        ],
    ],
    'customer' => [
        'email' => 'demo@example.com',
    ],
    'metadata' => [
        'biz_order_no' => 'A20260414001',
    ],
];
```

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

### Alipay HK Configuration

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/pay.md

Example configuration for Alipay HK, requiring the os_type specification.

```php
$order = [
    '_native_api' => true,
    'amount' => 100,
    'currency' => 'USD',
    'merchant_order_id' => 'order_20260414_001',
    'payment_method' => [
        'type' => 'alipayhk',
        'alipayhk' => [
            'flow' => 'mobile_web',
            'os_type' => 'android', // ios / android
        ],
    ],
];
```

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

### Pay::alipay()->web()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/alipay/pay.md

Initiates a web-based Alipay payment. Supports an optional '_method' parameter set to 'get' for GET requests.

```APIDOC
## Pay::alipay()->web(array $order)

### Description
Initiates a web payment request. The SDK automatically handles mandatory parameters like product_code.

### Parameters
- **$order** (array) - Required - Order configuration parameters as defined by Alipay official documentation.

### Request Example
```php
Pay::alipay()->web([
    'out_trade_no' => ''.time(),
    'total_amount' => '0.01',
    'subject' => 'yansongda 测试 - 1',
]);
```
```

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

### Virtual Payment Callback Response Formats

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/wechat/virtual.md

Examples of returning success responses in XML or JSON formats.

```xml
<xml>
  <ErrCode>0</ErrCode>
  <ErrMsg>success</ErrMsg>
</xml>
```

```php
return Pay::wechat()->success(['_action' => 'virtual', '_format' => 'json']);
// {"ErrCode":0,"ErrMsg":"success"}
```

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

### WeChat Pay Configuration

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/pay.md

Example configuration for WeChat Pay using the mobile_web flow.

```php
$order = [
    '_native_api' => true,
    'amount' => 100,
    'currency' => 'USD',
    'merchant_order_id' => 'order_20260414_001',
    'payment_method' => [
        'type' => 'wechatpay',
        'wechatpay' => [
            'flow' => 'mobile_web',
        ],
    ],
];

$result = Pay::airwallex()->intent($order);
```

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

### Pay::alipay()->h5()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/alipay/pay.md

Initiates an H5-based Alipay payment. Supports an optional '_method' parameter set to 'get' for GET requests.

```APIDOC
## Pay::alipay()->h5(array $order)

### Description
Initiates an H5 payment request. The SDK automatically handles mandatory parameters.

### Parameters
- **$order** (array) - Required - Order configuration parameters as defined by Alipay official documentation.

### Request Example
```php
Pay::alipay()->h5([
    'out_trade_no' => time(),
    'total_amount' => '0.01',
    'subject' => 'yansongda 测试 - 01',
    'quit_url' => 'https://yansongda.cn',
 ]);
```
```

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

### 网页支付示例

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/alipay/pay.md

标准网页支付调用，支持通过添加 _method => get 参数切换为 GET 提交方式。

```php
Pay::config($this->config);

return Pay::alipay()->web([
    'out_trade_no' => ''.time(),
    'total_amount' => '0.01',
    'subject' => 'yansongda 测试 - 1',
]);
```

```php
Pay::config($this->config);

return Pay::alipay()->web([
    'out_trade_no' => ''.time(),
    'total_amount' => '0.01',
    'subject' => 'yansongda 测试 - 1',
    '_method' => 'get',
]);
```

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

### Execute Alipay API with Plugins

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/alipay/all.md

Demonstrates how to configure the payment instance and execute a request by passing an array of plugins to the pay method.

```php
Pay::config($config);

$params = [
    'out_trade_no' => '1514027114',
];

$allPlugins = [StartPlugin::class, QueryPlugin::class, FormatPayloadBizContentPlugin::class, AddPayloadSignaturePlugin::class, AddRadarPlugin::class, VerifySignaturePlugin::class, ResponsePlugin::class, ParserPlugin::class];

$result = Pay::alipay()->pay($allPlugins, $params);
```

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

### 获取支付结果链接

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/quick-start/airwallex.md

根据响应中的 next_action 类型提取支付链接，或直接使用 SDK 提供的便捷字段。

```php
$payUrl = '';
$type = $result->get('next_action.type', '');

switch ($type) {
    case 'render_qrcode':
        $payUrl = $result->get('next_action.qrcode_url')
            ?? $result->get('next_action.url', '');
        break;
    case 'redirect':
        $payUrl = $result->get('next_action.url', '');
        break;
}
```

```php
$payUrl = $result->get('pay_url');
$paymentIntentId = $result->get('payment_intent_id');
$nextActionType = $result->get('next_action_type');
```

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

### H5 支付示例

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/alipay/pay.md

H5 支付调用示例，支持通过 _method => get 参数切换请求方式。

```php
Pay::config($this->config);

return Pay::alipay()->h5([
    'out_trade_no' => time(),
    'total_amount' => '0.01',
    'subject' => 'yansongda 测试 - 01',
    'quit_url' => 'https://yansongda.cn',
 ]);
```

```php
Pay::config($this->config);

return Pay::alipay()->h5([
    'out_trade_no' => ''.time(),
    'total_amount' => '0.01',
    'subject' => 'yansongda 测试 - 1',
    '_method' => 'get',
]);
```

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

### Pay::alipay()->mini()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/alipay/pay.md

Initiates an Alipay mini-program payment.

```APIDOC
## Pay::alipay()->mini(array $order)

### Description
Initiates a mini-program payment request. Returns a Collection object.

### Parameters
- **$order** (array) - Required - Order configuration parameters as defined by Alipay official documentation.

### Request Example
```php
$result = Pay::alipay()->mini([
    'out_trade_no' => time().'',
    'total_amount' => '0.01',
    'subject' => 'yansongda 测试 - 01',
    'buyer_id' => '2088622190161234',
]);
```
```

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

### Pay::airwallex()->intent($order)

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/pay.md

初始化 Airwallex 支付意图。根据传入的 $order 参数，SDK 会调用 Airwallex 的创建接口，若开启 Native API 模式则会自动调用确认接口。

```APIDOC
## Method: intent

### Description
初始化 Airwallex 支付意图。该方法支持默认模式（仅创建）和 Native API 模式（创建并确认）。

### Parameters
- **$order** (array) - Required - 包含支付信息的订单数组，支持参数包括 amount, currency, merchant_order_id, _native_api, return_url, payment_method, payment_method_options, customer_id, customer, descriptor, order, metadata 等。

### Usage Example
```php
$order = [
    'amount' => 100,
    'currency' => 'USD',
    'merchant_order_id' => 'order_20260414_001'
];

$result = Pay::airwallex()->intent($order);
```

### Native API Usage
若需使用 Native API 模式，请在 $order 中显式传入 '_native_api' => true。
```php
$order = [
    '_native_api' => true,
    'amount' => 100,
    'currency' => 'USD',
    'merchant_order_id' => 'order_20260414_001',
    'payment_method' => ['type' => 'card', ...]
];

$result = Pay::airwallex()->intent($order);
```
```

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

### Pay::alipay()->app()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/alipay/pay.md

Initiates an APP-based Alipay payment.

```APIDOC
## Pay::alipay()->app(array $order)

### Description
Initiates an APP payment request. Please refer to official Alipay documentation for APP-side integration.

### Parameters
- **$order** (array) - Required - Order configuration parameters as defined by Alipay official documentation.

### Request Example
```php
Pay::alipay()->app([
    'out_trade_no' => time(),
    'total_amount' => '0.01',
    'subject' => 'yansongda 测试 - 01',
]);
```
```

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

### 配置虚拟支付沙箱环境

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/wechat/virtual.md

在订单参数中设置 env 为 1 以使用沙箱环境进行测试。

```php
$order = [
    'buyQuantity' => 100,
    'productId' => 'product_001',
    'goodsPrice' => 1,
    'outTradeNo' => time().'',
    'env' => 1, // 沙箱环境
];

$result = Pay::wechat()->virtual($order);
```

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

### 基础回调处理

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/callback.md

配置支付参数后，调用 callback 方法处理 Airwallex 回调。

```php
Pay::config($config);

$result = Pay::airwallex()->callback();
```

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

### Pay::unipay()->web()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/unipay/pay.md

Initiates a computer-based web payment.

```APIDOC
## Pay::unipay()->web()

### Description
Initiates a web-based payment for desktop environments.

### Parameters
- **$order** (array) - Required - Order configuration parameters as defined by UnionPay official documentation.

### Request Example
```php
Pay::unipay()->web([
    'txnTime' => '20231027100000',
    'txnAmt' => 1,
    'orderId' => 'yansongda20231027100000',
]);
```
```

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

### Switch Configuration for Multi-tenancy

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/quick-start/init.md

Switch between different tenant configurations by passing the _config parameter during service calls.

```php
Pay::config($this->config);

$order = [
    'out_trade_no' => '1514027114',
    '_config' => 'default', // 注意这一行
];

$result = Pay::alipay()->find($order);
```

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

### 配置 Airwallex 支付参数

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/quick-start/airwallex.md

在应用启动时通过 Pay::config 方法设置 Airwallex 的客户端凭证、Webhook 密钥及运行环境。

```php
use Yansongda\Pay\Pay;

$config = [
    'airwallex' => [
        'default' => [
            // 「必填」Airwallex Client ID
            'client_id' => '',
            // 「必填」Airwallex API Key
            'api_key' => '',
            // 「必填」Webhook Secret，用于回调验签
            'webhook_secret' => '',
            // 「选填」支付完成后的返回地址
            'return_url' => 'https://example.com/airwallex/return',
            // 「选填」Airwallex API 版本
            'api_version' => '2024-06-14',
            // 「选填」平台模式代商户调用时使用
            // 'on_behalf_of' => 'open_id_xxx',
            // 「选填」默认为正式模式。可选值：
            // MODE_NORMAL: 正式环境
            // MODE_SANDBOX: 沙箱环境
            'mode' => Pay::MODE_NORMAL,
        ],
    ],
];

Pay::config($config);
```

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

### 处理回调通知

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/quick-start/airwallex.md

接收并验证 Airwallex 的异步回调通知。

```php
$result = Pay::airwallex()->callback();

return Pay::airwallex()->success();
```

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

### 更新依赖库

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/upgrade/v3.3.md

在非 hyperf/laravel 框架或无框架环境下，需手动替换依赖库。

```shell
composer remove php-di/php-di && composer require hyperf/pimple
```

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

### Pay::unipay()->query()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/unipay/query.md

查询银联订单状态的方法，支持普通支付订单和退款订单查询。

```APIDOC
## Method: Pay::unipay()->query(array $order)

### Description
查询银联支付订单或退款订单的详细信息。该方法兼容银联官方接口参数。

### Parameters
- **$order** (array) - Required - 包含查询条件的订单数组。对于普通支付，通常包含 'txnTime' 和 'orderId'；对于退款，通常包含 'out_trade_no' 和 'out_refund_no'。

### Returns
- **Collection** - 包含查询结果的集合对象。

### Example
```php
$order = [
    'txnTime' => '20220911041647',
    'orderId' => 'pay20220911041647',
];

$result = Pay::unipay()->query($order);
```
```

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

### Pay::douyin()->mini()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/douyin/pay.md

发起抖音小程序支付请求，返回包含订单信息的 Collection 对象。

```APIDOC
## Method: Pay::douyin()->mini()

### Description
发起抖音小程序支付请求。扩展包会自动处理 app_id 和 sign 等客观参数，用户仅需传入订单主观参数。

### 参数
- **$order** (array) - 订单参数，具体字段请参考抖音官方文档「请求参数」一栏。

### 返回值
- **Collection** - 包含订单响应数据的集合，可通过 $result->data['order_id'] 等方式访问。

### 调用示例
```php
Pay::config($config);

$order = [
    'out_order_no' => date('YmdHis').rand(1000, 9999),
    'total_amount' => 1,
    'subject' => '闫嵩达 - test - subject - 01',
    'body' => '闫嵩达 - test - body - 01',
    'valid_time' => 600,
];

$result = Pay::douyin()->mini($order);
```
```

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

### 退款

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/quick-start/alipay.md

发起退款请求，可通过 _action 参数指定退款类型。

```php
Pay::config($this->config);

$result = Pay::alipay()->refund([
    'out_trade_no' => '1623160012',
    'refund_amount' => '0.01',
    // '_action' => 'agreement', // 商家收款退款
    // '_action' => 'authorization', // 预授权退款
    // '_action' => 'transfer', // 转账退款
]);
```

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

### Pay::stripe()->web($order)

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/stripe/pay.md

创建 Checkout Session，适用于托管支付页面场景，由 Stripe 托管结账流程。

```APIDOC
## Pay::stripe()->web($order)

### Description
创建 Checkout Session，适用于托管支付页面场景，用户完成支付后跳转回指定页面。

### Parameters
- **$order** (array) - Required - 订单配置参数，参考 Stripe 官方 Checkout Sessions API 文档。

### Response
- **Collection** - 返回包含 url 的集合对象，用于重定向用户至 Stripe Checkout 页面。
```

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

### Pay::douyin()->query()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/douyin/query.md

Queries Douyin payment or refund orders based on the provided configuration array.

```APIDOC
## Method: Pay::douyin()->query(array $order)

### Description
Queries the status of a Douyin payment or refund order. The behavior is determined by the `_action` parameter within the order array.

### Parameters
- **$order** (array) - Required - An associative array containing order identification details. 
  - `out_order_no` (string) - Required for payment queries - The merchant order number.
  - `transaction_id` (string) - Required for refund queries - The transaction ID.
  - `_action` (string) - Optional - Specifies the query type. Use 'refund' or 'refund_mini' for refund queries; defaults to 'mini' for payment queries.

### Usage Example
```php
$order = [
    'out_order_no' => '202408040747147327'
];
$result = Pay::douyin()->query($order);
```

### Returns
- **Collection** - A collection object containing the order query result.
```

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

### Pay::paypal()->web($order)

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/paypal/pay.md

通过 SDK 创建 PayPal 订单。传入订单参数数组，返回包含支付链接的 Collection 对象。

```APIDOC
## Method: Pay::paypal()->web($order)

### Description
创建 PayPal 订单。用户在商户侧发起支付后，调用此方法创建订单，并从返回结果的 links 中获取 approve 类型的链接以重定向用户至 PayPal 授权页面。

### Parameters
- **$order** (array) - Required - 订单参数，包含 purchase_units 等官方 API 定义的参数。支持传入 _access_token 进行自定义令牌管理。

### Response
- **Collection** - 包含订单详情及 links 数组的集合对象。
```

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

### Simplified Response Handling with Convenience Fields

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/pay.md

Use the SDK's pre-processed convenience fields to simplify response handling.

```php
$result = Pay::airwallex()->intent($order);

return [
    'payment_intent_id' => $result->get('payment_intent_id'),
    'pay_url' => $result->get('pay_url'),
    'next_action_type' => $result->get('next_action_type'),
    'raw' => $result,
];
```

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

### 更新 composer 依赖

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/upgrade/v3.1.md

在 composer.json 中修改版本号并执行更新。

```shell
composer update
```

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

### Airwallex Native API 支付模式

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/pay.md

通过显式传入 _native_api => true，在服务端完成支付创建与确认流程。

```php
$order = [
    '_native_api' => true,
    'amount' => 100,
    'currency' => 'USD',
    'merchant_order_id' => 'order_20260414_001',
    'payment_method' => [
        'type' => 'card',
        'card' => [
            'number' => '4111111111111111',
            'expiry_month' => '12',
            'expiry_year' => '2030',
            'name' => 'John Doe',
            'cvc' => '123',
        ],
    ],
];

$result = Pay::airwallex()->intent($order);
```

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

### 运行时附加参数

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/callback.md

通过第二个参数传递运行时配置，例如切换租户。

```php
$result = Pay::airwallex()->callback(null, [
    '_config' => 'other',
]);
```

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

### Execute PayPal API Call with Plugins

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/paypal/all.md

Configures the payment environment and executes a sequence of plugins to process a PayPal request.

```php
Pay::config($config);

$params = [
    'order_id' => '5O190127TN364715T',
];

$allPlugins = [StartPlugin::class, ObtainAccessTokenPlugin::class, QueryPlugin::class, AddPayloadBodyPlugin::class, AddRadarPlugin::class, ResponsePlugin::class, ParserPlugin::class];

$result = Pay::paypal()->pay($allPlugins, $params);
```

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

### Initialize Pay Service

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/quick-start/init.md

Methods for initializing the Pay service globally or during specific calls, with options to force configuration overrides.

```php
Pay::config($config);
```

```php
Pay::config(array_merge($config, ['_force' => true]));
```

```php
Pay::alipay($config)->web($order);
```

```php
Pay::alipay(array_merge($config, ['_force' => true]))->web($order);
```

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

### Pay::unipay()->refund()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/unipay/cancel.md

用于 QRA 平台刷卡支付的订单取消（退款）操作。

```APIDOC
## Method: Pay::unipay()->refund()

### Description
针对 QRA 平台刷卡支付场景进行订单取消或退款操作。

### Parameters
- **$order** (array) - Required - 包含订单信息的数组，必须包含 '_action' => 'qra_pos'。

### Example
```php
$result = Pay::unipay()->refund([
    'out_trade_no' => date('YmdHis'),
    '_action' => 'qra_pos',
]);
```
```

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

### Pay::douyin()->callback()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/douyin/callback.md

处理抖音支付回调请求，返回包含回调参数的 Collection 实例。

```APIDOC
## Pay::douyin()->callback()

### Description
处理抖音支付回调请求。该方法会自动解析请求数据并返回处理后的参数集合。

### Parameters
- **request** (null|array|ServerRequestInterface) - Optional - 回调请求数据。若为 null 则自动识别；若为 ServerRequestInterface 则适用于 swoole 环境；若为 array 则使用手动解析的参数。
- **config** (array) - Optional - 自定义配置变量，例如使用 `['_config' => 'tenant_name']` 切换租户配置。

### Usage Example
```php
Pay::config($this->config);
$result = Pay::douyin()->callback();
```
```

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

### 查询订单

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/quick-start/alipay.md

查询订单状态，可通过 _action 参数指定查询类型。

```php
Pay::config($this->config);

$order = [
    'out_trade_no' => '1514027114',
    // '_action' => 'agreement', // 商家收款查询
    // '_action' => 'authorization', // 预授权查询
    // '_action' => 'transfer', // 转账查询
    // '_action' => 'face' // 刷脸结果信息查询
    // '_action' => 'transfer' // 转账查询
    // '_action' => 'refund' // 退款查询
];

$result = Pay::alipay()->query($order);
```

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

### Pay::unipay()->callback()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/unipay/callback.md

处理银联支付回调请求，返回包含处理结果的 Collection 实例。

```APIDOC
## callback

### Description
处理银联支付的回调请求。该方法支持自动识别请求，或通过传入参数手动处理，适用于多种运行环境。

### 方法签名
`callback(mixed $data = null, array $config = [])`

### 参数
- **$data** (null|array|ServerRequestInterface) - 可选 - 回调数据。若为 null，系统自动识别；若为 array，则使用传入的数组；若为 ServerRequestInterface，适用于 Swoole 环境。
- **$config** (array) - 可选 - 自定义配置变量，如通过 `_config` 指定特定租户配置。

### 返回值
- **Collection** - 包含处理后的回调参数。

### 示例
```php
Pay::config($this->config);

// 自动处理回调
$result = Pay::unipay()->callback();

// 使用自定义配置处理回调
$result = Pay::unipay()->callback(null, ['_config' => 'yansongda']);
```
```

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

### success()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/unipay/response.md

该方法用于向银联发送确认回调的响应。调用此方法后，系统将返回一个标准的响应对象。

```APIDOC
## success()

### Description
该方法用于向银联发送确认回调的响应，告知银联已成功接收并处理回调通知。

### Method
PHP Method

### Parameters
- 无

### Response
- **Response** (Object) - 返回一个响应对象，用于结束回调处理流程。

### Example
```php
return Pay::unipay()->success();
```
```

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

### Pay::stripe()->query()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/stripe/query.md

查询 Stripe 支付或退款订单的通用方法。

```APIDOC
## Stripe::query

### Description
查询 Stripe 支付订单或退款订单信息。

### Method
PHP Method

### Signature
`Pay::stripe()->query(array $order)`

### Parameters
- **$order** (array) - Required - 包含查询条件的数组。对于支付订单，需包含 'payment_intent_id'；对于退款订单，需包含 'refund_id' 和 '_action' => 'refund'。

### Returns
- **Collection** - 返回包含订单详情的集合对象。

### Example
```php
// 查询支付订单
$order = ['payment_intent_id' => 'pi_3OxxxxxxxxxxxxxxxxxxxxY'];
$result = Pay::stripe()->query($order);

// 查询退款订单
$order = ['refund_id' => 're_3OxxxxxxxxxxxxxxxxxxxxY', '_action' => 'refund'];
$result = Pay::stripe()->query($order);
```
```

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

### Pay::unipay()->h5()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/unipay/pay.md

Initiates an H5 mobile payment.

```APIDOC
## Pay::unipay()->h5()

### Description
Initiates an H5 payment for mobile browsers.

### Parameters
- **$order** (array) - Required - Order configuration parameters as defined by UnionPay official documentation.

### Request Example
```php
Pay::unipay()->h5([
    'txnTime' => '20231027100000',
    'txnAmt' => 1,
    'orderId' => 'yansongda20231027100000',
]);
```
```

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

### success()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/douyin/response.md

向抖音服务器发送确认响应，表示回调已成功处理。

```APIDOC
## success()

### Description
该方法用于在接收并处理抖音支付回调后，向抖音服务器返回确认响应。

### Method
PHP Method

### Parameters
- **无**

### Response
- **Response** (Object) - 返回确认响应对象。

### Example
```php
return Pay::douyin()->success();
```
```

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

### 常驻内存环境回调处理

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/callback.md

在 Swoole 或 Hyperf 等常驻内存环境中，显式传入 ServerRequestInterface 对象。

```php
$result = Pay::airwallex()->callback($request);
```

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

### Pay::alipay()->scan()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/alipay/pay.md

Initiates a scan-to-pay Alipay payment.

```APIDOC
## Pay::alipay()->scan(array $order)

### Description
Initiates a scan payment request. Returns a Collection object containing the QR code URL.

### Parameters
- **$order** (array) - Required - Order configuration parameters as defined by Alipay official documentation.

### Request Example
```php
$result = Pay::alipay()->scan([
    'out_trade_no' => time(),
    'total_amount' => '0.01',
    'subject' => 'yansongda 测试 - 01',
]);
```
```

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

### SDK Directory Structure

Source: https://github.com/yansongda/pay/blob/master/AGENTS.md

The file system layout of the yansongda/pay SDK, highlighting key directories for configuration, plugins, and providers.

```text
src/
├── Config/           # Typed Config（WechatConfig、AlipayConfig 等）
├── Event/            # PSR-14 事件
├── Plugin/{Provider}/V{n}/
├── Provider/         # Alipay、Wechat 等
├── Shortcut/{Provider}/
├── Traits/           # {Provider}Trait、ProviderConfigTrait
├── CertManager.php   # 证书缓存
└── Pay.php
```

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

### 处理支付回调

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/quick-start/jsb.md

使用 callback 方法解析并处理银行发送的异步通知。

```php
Pay::config($this->config);

$result = Pay::jsb()->callback();
```

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

### Pay::unipay()->scan()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/unipay/pay.md

Initiates a scan-to-pay transaction.

```APIDOC
## Pay::unipay()->scan()

### Description
Initiates a scan-based payment. Returns a Collection containing the QR code URL.

### Parameters
- **$order** (array) - Required - Order configuration parameters including optional '_action' for specific types like 'pre_auth' or 'pre_order'.

### Request Example
```php
Pay::unipay()->scan([
    'txnTime' => '20231027100000',
    'txnAmt' => 1,
    'orderId' => 'scan20231027100000',
]);
```
```

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

### Handling Payment Next Actions in PHP

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/pay.md

Implement logic to extract the payment URL based on the next action type.

```php
$payUrl = '';
$type = $result->get('next_action.type', '');

switch ($type) {
    case 'render_qrcode':
        $payUrl = $result->get('next_action.qrcode_url')
            ?? $result->get('next_action.url', '');
        break;
    case 'redirect':
        $payUrl = $result->get('next_action.url', '');
        break;
}
```

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

### APP 支付示例

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/alipay/pay.md

APP 支付调用示例，具体 APP 端集成请参考支付宝官方文档。

```php
Pay::config($this->config);

// 后续 APP 调用方式不在本文档讨论范围内，请参考官方文档。
return Pay::alipay()->app([
    'out_trade_no' => time(),
    'total_amount' => '0.01',
    'subject' => 'yansongda 测试 - 01',
]);
```

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

### Compose Custom Airwallex Plugin Chain

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/all.md

Use this approach to manually assemble a sequence of plugins for specific Airwallex API interactions.

```php
$allPlugins = [StartPlugin::class, ObtainAccessTokenPlugin::class, \Yansongda\Pay\Plugin\Airwallex\V1\Pay\QueryPlugin::class, AddPayloadBodyPlugin::class, AddRadarPlugin::class, ResponsePlugin::class, ParserPlugin::class];

$result = Pay::airwallex()->pay($allPlugins, [
    'payment_intent_id' => 'int_xxx',
]);
```

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

### 调用银联 API 插件

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/unipay/all.md

使用 Pay::unipay()->pay() 方法配合插件数组执行银联 API 调用。

```php
Pay::config($config);

$params = [
    'out_trade_no' => '1514027114',
];

$allPlugins = [StartPlugin::class, QueryPlugin::class, AddPayloadSignaturePlugin::class, AddPayloadBodyPlugin::class, AddRadarPlugin::class, VerifySignaturePlugin::class, ParserPlugin::class];

$result = Pay::unipay()->pay($allPlugins, $params);
```

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

### Pay::jsb()->callback()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/jsb/callback.md

处理江苏银行e融支付的回调请求，返回一个包含处理结果的Collection实例。

```APIDOC
## Pay::jsb()->callback()

### Description
处理江苏银行e融支付的回调请求。该方法支持自动识别请求，或手动传入请求数据以适应不同环境。

### Parameters
- **$data** (null|array|ServerRequestInterface) - Optional - 请求数据。若为null，则自动识别；若为ServerRequestInterface，推荐在swoole环境下使用；若为array，则手动传入解析后的参数。
- **$config** (array) - Optional - 自定义配置参数，例如通过 ['_config' => 'tenant_name'] 切换租户配置。

### Returns
- **Collection** - 包含回调处理结果的集合对象。

### Example
```php
Pay::config($this->config);
$result = Pay::jsb()->callback();
```
```

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

### Pay::unipay()->refund()

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/unipay/refund.md

执行银联退款操作。该方法接收一个包含订单信息的数组，并返回一个 Collection 对象。

```APIDOC
## Method: Pay::unipay()->refund(array $order)

### Description
执行银联退款操作。支持在线网关、二维码退款以及 QRA 平台刷卡支付退款。

### Parameters
- **$order** (array) - Required - 包含退款请求参数的数组。参数与银联官方文档保持一致。

### Usage Examples

#### 在线网关/二维码退款
```php
$result = Pay::unipay()->refund([
    'txnTime' => date('YmdHis'),
    'txnAmt' => 1,
    'orderId' => 'refund'.date('YmdHis'),
    'origQryId' => '392209121420295251518',
    // '_action' => 'web', // 网页退款，默认
    // '_action' => 'qr_code', // 二维码退款
]);
```

#### QRA 平台刷卡支付退款
```php
$result = Pay::unipay()->refund([
    'out_trade_no' => date('YmdHis'),
    'out_refund_no' => 'refund'.date('YmdHis'),
    'total_fee' => 1,
    'refund_fee' => 1,
    'op_user_id' => '123',
    '_action' => 'qra_pos',
]);
```

### Returns
- **Collection** - 包含退款响应结果的集合对象。
```

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

### Enable Native API

Source: https://github.com/yansongda/pay/blob/master/web/docs/v3/airwallex/pay.md

Set the _native_api parameter to true to trigger both payment intent creation and confirmation.

```php
'_native_api' => true
```
Tokens:
Raw