README

MVola 扩展包是一个提供与 MVola 支付网关集成的 Symfony 扩展包。它提供了一个方便的方式与 MVola API 交互、处理交易和管理回调。

功能

与 Symfony 项目轻松集成
处理 MVola API 认证
提供启动交易、检查交易状态和检索交易详情的服务
包含处理 MVola 通知的回调处理程序
可配置的 API 调用重试机制
支持缓存认证令牌

安装

您可以使用 Composer 安装 MVola 扩展包

composer require dahromy/mvola-bundle

配置

安装扩展包后，您需要在您的 Symfony 应用程序中对其进行配置。将以下内容添加到您的 config/packages/mvola.yaml 文件中

mvola:
    environment: '%env(MVOLA_ENVIRONMENT)%'
    merchant_number: '%env(MVOLA_MERCHANT_NUMBER)%'
    company_name: '%env(MVOLA_COMPANY_NAME)%'
    consumer_key: '%env(MVOLA_CONSUMER_KEY)%'
    consumer_secret: '%env(MVOLA_CONSUMER_SECRET)%'
    auth_url: '%env(MVOLA_AUTH_URL)%'
    max_retries: 3
    retry_delay: 1000
    cache_ttl: 3600

请确保在您的 .env 文件中设置相应的环境变量

MVOLA_ENVIRONMENT=sandbox
MVOLA_CONSUMER_KEY=your_consumer_key_here
MVOLA_CONSUMER_SECRET=your_consumer_secret_here
MVOLA_MERCHANT_NUMBER=your_merchant_number_here
MVOLA_COMPANY_NAME=your_company_name_here
MVOLA_AUTH_URL=https://sandbox.mvola.mg/token

使用

启动交易

要启动交易，您可以使用 MVolaService

use DahRomy\MVola\Service\MVolaService;
use DahRomy\MVola\Model\TransactionRequest;

class PaymentController extends AbstractController
{
    private $mvolaService;

    public function __construct(MVolaService $mvolaService)
    {
        $this->mvolaService = $mvolaService;
    }

    public function initiatePayment()
    {
        $transactionRequest = new TransactionRequest();
        $transactionRequest->setAmount(1000)
            ->setCurrency('Ar')
            ->setDescriptionText('Payment for order #123')
            ->setRequestingOrganisationTransactionReference('123456')
            ->setRequestDate(new \DateTime())
            ->setOriginalTransactionReference('123456')
            ->setDebitParty([['key' => 'msisdn', 'value' => '0343500003']])
            ->setCreditParty([['key' => 'msisdn', 'value' => '0343500004']])
            ->setMetadata([
                ['key' => 'partnerName', 'value' => 'Partner Name'],
                ['key' => 'fc', 'value' => 'USD'],
                ['key' => 'amountFc', 'value' => '1']
            ])
            ->setCallbackData([
                'userId' => '123456',
                // ... other callback data
            ]);

        $result = $this->mvolaService->initiateTransaction($transactionRequest);

        // Handle the result
    }
}

检查交易状态

要检查交易状态

$status = $this->mvolaService->getTransactionStatus($serverCorrelationId);

检索交易详情

要获取交易详情

$details = $this->mvolaService->getTransactionDetails($transactionId);

处理回调

MVola 扩展包提供了一个内置的回调处理程序，用于处理来自 MVola 的回调。要在您的应用程序中处理这些回调，请按照以下步骤操作

创建事件订阅者

use DahRomy\MVola\Event\MVolaCallbackEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class MVolaCallbackSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            MVolaCallbackEvent::NAME => 'onMVolaCallback',
        ];
    }

    public function onMVolaCallback(MVolaCallbackEvent $event): void
    {
        // Response data from MVola
        $mvolaData = $event->getMVolaData();
        
        // Callback data sent with the transaction request
        $callbackData = $event->getCallbackData();

        // Process the callback data
        // For example, update the transaction status in your database
        // or trigger any necessary business logic
    }
}

在您的 services.yaml 中注册您的事件订阅者

services:
    App\EventSubscriber\MVolaCallbackSubscriber:
        tags:
            - { name: kernel.event_subscriber }

配置回调 URL

在启动交易时，您可以包含自定义回调数据

$transactionRequest = new TransactionRequest();
// ... set other transaction details ...
$transactionRequest->setCallbackData([
    'orderId' => '123456',
    'customerId' => '789',
]);

$result = $this->mvolaService->initiateTransaction($transactionRequest);

MVola 扩展包将自动处理在 /mvola/callback 端点接收到的回调。当接收到回调时，它将

记录接收到的回调数据
分发 MVolaCallbackEvent

您的事件订阅者将根据您应用程序的需求处理回调数据

您还可以通过在 TransactionRequest 对象中设置 callbackUrl 属性来自定义回调 URL

$transactionRequest->setCallbackUrl('https://example.com/mvola/callback');

注意：请确保您的服务器配置为在回调 URL 接受 PUT 请求，因为 MVola 使用 PUT 方法发送回调

错误处理

扩展包针对不同的错误场景抛出特定的异常。请确保在您的应用程序中捕获和处理这些异常

MVolaApiException：用于一般 API 错误
MVolaAuthenticationException：用于与认证相关的错误
MVolaValidationException：用于请求数据中的验证错误
MVolaNetworkException：用于与网络相关的错误
MVolaRateLimitException：用于速率限制错误

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

此扩展包是开源软件，根据 MIT 许可证发布。

dahromy / mvola-bundle

维护者

详细信息