跳到正文

Laravel 扩展包

在您的 Laravel 应用中接受加密货币支付

用 ArionPay::createInvoice 创建账单,并在 InvoicePaid 监听器中交付订单。扩展包会为您校验签名、测试或正式模式以及重复投递。

安装

composer require arionpay/arionpay-laravel
GitHub 上的源代码
示例

功能介绍

面向 Laravel 开发者的 ArionPay

arionpay/arionpay-laravel 基于官方 PHP 开发库构建,适用于 PHP 8.1 或更高版本上的 Laravel 10 至 13。它会添加一个 Webhook 路由,校验每个签名更新,并将其作为普通 Laravel 事件只触发一次。
阅读更多在测试模式下,每张新账单都是测试账单,因此您可以不用真钱试用整个流程。付款直接进入您自己的钱包:ArionPay 从不持有这些资金。
  • ArionPay::createInvoice([...]) 会返回支付页面地址(invoiceUrl)。
  • 付款更新以 Laravel 事件的形式到达:InvoicePaid、InvoicePending、InvoicePartial、InvoiceExpired、InvoiceNeedsReview 和 TestWebhookReceived。
  • 路由 POST /arionpay/webhook 基于原样的请求体校验 ArionPay-Signature(5 分钟时间窗口)。其他请求一律返回 401,不会触发任何事件。
  • 每个事件只触发一次:它会在您的缓存中记录 96 小时。
  • ARIONPAY_TEST_MODE=true 会让新账单都成为测试账单,并且只接受测试 Webhook。不一致时返回 409。
  • php artisan arionpay:check 会检查您的密钥并显示 Webhook 地址。php artisan arionpay:test-webhook 会请求 ArionPay 发送一个签名的示例事件。
  • 每个事件都提供 matches($amount, $currency)、invoiceId()、orderId() 和 metadata(),用于核对订单。

要求与许可证

适用于
Laravel 10 至 13 · PHP 8.1 或更高版本 · 基于 arionpay/arionpay-php 构建
测试情况
Laravel 13.42 和 12,连接真实的 ArionPay 服务器测试
费用
开发库免费。ArionPay 每笔付款收取 0.5% 手续费,无月费。
源代码
在 GitHub 上开源(MIT)。

设置

5 步完成设置

  1. 第 1 步

    安装软件包

    运行 composer require arionpay/arionpay-laravel。Laravel 会自动发现服务提供者和 ArionPay Facade。

  2. 第 2 步

    将您的密钥加入 .env

    用 ArionPay 控制台中的值设置 ARIONPAY_API_KEY(pk_)、ARIONPAY_API_SECRET(sk_)和 ARIONPAY_WEBHOOK_SECRET(whsec_),并设置 ARIONPAY_TEST_MODE=true。然后运行 php artisan arionpay:check。

  3. 第 3 步

    创建账单

    用金额、orderId 和 idempotencyKey(例如 'order-' . $order->id)调用 ArionPay::createInvoice,并重定向到 $invoice['invoiceUrl']。除非您传入自己的 callbackUrl,否则账单会把更新发送到您应用的 Webhook 路由。

  4. 第 4 步

    在 InvoicePaid 时交付

    监听 ArionPay\Laravel\Events\InvoicePaid,找到对应订单,检查 $event->matches($order->total, $order->currency),然后交付。如果监听器抛出异常,路由会返回 500,ArionPay 稍后会再次投递。

  5. 第 5 步

    先测试,再上线

    在测试模式下,用 'asset' => 'USDT_TRC20' 创建账单并调用 ArionPay::simulatePayment($invoice['id'], 'exact'),或使用控制台中的“Try a test payment”按钮。如需真实付款,请设置 ARIONPAY_TEST_MODE=false。

设置完成后

付款如何到达您的代码

  • InvoicePaid:已全额支付并确认,可以交付。逾期付款、差额在您付款容差(默认 1%)以内的付款,以及您在 Payment Radar 中接受的付款,也会触发此事件。
  • InvoicePending:已在网络上发现付款,正在等待确认。请暂勿交付。
  • InvoicePartial 和 InvoiceExpired:未全额支付。之后仍可能有逾期付款到账,并触发 InvoicePaid。
  • InvoiceNeedsReview:请在您的 ArionPay 控制台中决定。如果您接受,随后会触发 InvoicePaid。
  • TestWebhookReceived:由“Send test webhook”发送的示例,涉及的是一张虚构的账单。切勿因此交付。

9 个网络上的 16 种币和代币

全部币种
  • BTCBitcoin
  • ETHEthereum
  • USDTEthereum
  • USDCEthereum
  • BNBBNB Smart Chain
  • USDTBNB Smart Chain
  • USDCBNB Smart Chain
  • POLPolygon
  • USDTPolygon
  • USDCPolygon
  • TRXTRON
  • USDTTRON
  • LTCLitecoin
  • DOGEDogecoin
  • BCHBitcoin Cash
  • DASHDash

关于 ArionPay Laravel 开发库的问题

将它加入代码之前需要了解的简短解答。

支持 Laravel 10 至 13,需要 PHP 8.1 或更高版本。已在 Laravel 13.42 和 12 上连接真实的 ArionPay 服务器进行测试。