README

一个laravel-php包，用于简化您应用中guhemba支付API的集成

官方文档

从版本 >=3.0.0 开始，您可以在以下链接找到官方文档

旧版本文档（<=v2.1.2）

在此页面上，您将看到该包从v0到v2.1.2的文档

1. 前提条件

laravel框架

2. 安装

 composer require rwbuild/guhemba-web-element

3. 配置

3.1 发布配置文件

此配置涉及使用单个商户钱包接收支付的系统。为了开始享受此包，您需要发布支持Guhemba的配置文件

 php artisan vendor:publish --tag=config

运行此命令后，您应该在config目录下看到一个名为guhemba-webelement的文件，然后您需要在该文件中提供所有必要的信息。

3.2 闭合合作伙伴的配置

如果您没有Guhemba合作伙伴密钥，则应跳过本节。否则，请确保在所有请求的顶部放置以下代码

    \RWBuild\Guhemba\Facades\Guhemba::partnerKeys([
        'GUHEMBA_PUBLIC_PARTNER_KEY' => 'request-this-on-guhemba',
        'GUHEMBA_PARTNER_KEY' => 'request-this-on-guhemba',
        'GUHEMBA_BASE_URL' => 'guhemba-base-url'// Ask guhemba support team
    ]);

我建议您将上述代码放在您的服务提供者类中的一个boot方法中，然后您应该在您执行的每个请求中提供以下信息

    Guhemba::dynamicMerchant([
        'GUHEMBA_API_KEY' => 'wallet-merchant-integration-api-key',

        'GUHEMBA_MERCHANT_KEY' => 'wallet-merchant-key',

        'GUHEMBA_PUBLIC_KEY' => 'wallet-merchant-integration-public-key',

        'GUHEMBA_REDIRECT_URL' => 'your-dynamic-url'
    ]);

现在，我真的觉得您已经准备好了。让我们现在就开始享受这个包吧 😎。

4. 生成支付二维码

要生成支付二维码，您只需要在您的代码中放置以下脚本

    $amount = 1000;

    $paymentReference = 'order_id';

    $confirmPaymentKey = 'Unique_key';

    $qrcode = Guhemba::generateQrcode(
        $amount,
        $paymentReference,
        $confirmPaymentKey
    )->getQrcode();

注意：当您期望Guhemba在交易完成后向您发送反馈时，您应该在生成二维码时发送$paymentReference，这是客户购买的产品或产品组的参考。但是，您还需要在Guhemba钱包设置中提供payment_confirmation_endpoint。此端点必须接受POST请求。当交易完成时，它将被击中，并将包含以下响应

    [
        'payment_reference' => 'Your-provided-payment-ref',
        'transaction_token' => 'string',
        'confirm_payment_key' => 'string'
    ]

confirm_payment_key将帮助您保护您提供的payment_confirmation_endpoint，您应该在生成二维码后将其保存安全，因为它是一个唯一的密钥，将帮助您检查请求是否来自Guhemba。

5. 将用户重定向到Guhemba

因为Guhemba支付提供了一个很好的用户界面，其中将显示二维码，用户可以扫描它或决定点击支付按钮来完成在Guhemba上的支付。

假设，用户决定在Guhemba网站上完成支付，然后点击支付按钮，您需要将其重定向到Guhemba。要这样做，请看以下内容

    function redirectToGuhemba()
    {
        $qrcodeSlug ='91da-5a565f0b173c';
        $paymentRef = 6;

        return Guhemba::redirect($qrcodeSlug, $paymentRef)
    }

默认情况下，此方法将重定向用户到一个可以选择支付方式（卡、mtn等）的页面。这意味着如果已知用户将使用哪种方式支付，则可以将paymentOption传递给重定向方法

    function redirectToGuhemba()
    {
        $qrcodeSlug ='91da-5a565f0b173c';
        $paymentRef = 6;
        $paymentOption = "card";// can be:  mtn,card or choice(the default)

        return Guhemba::redirect($qrcodeSlug, $paymentRef,$paymentOption)
    }

二维码的slug，您将在生成二维码后获得，而paymentRef是客户想要支付订单的参考，此参考可以帮助您在客户完成在Guhemba上的支付后了解客户支付了哪种产品。

注意：请确保在Guhemba的config文件中正确设置了所有信息

如果需要在客户被重定向到guhemba之前检查格式化后的完整URL，我们提供了导出URL的功能。

    function redirectToGuhemba()
    {
        $qrcodeSlug ='91da-5a565f0b173c';
        $paymentRef = 6;

        return Guhemba::dump()->redirect($qrcodeSlug, $paymentRef)
    }

但是，该软件包还提供了一种通过记录来检查重定向完整URL的替代方法。

    function redirectToGuhemba()
    {
        $qrcodeSlug ='91da-5a565f0b173c';
        $paymentRef = 6;

        return Guhemba::shouldLog()->redirect($qrcodeSlug, $paymentRef)
    }

6. 获取交易信息

您可以通过不同的方式获取交易数据。

6.1 从回调获取交易信息

当用户在guhemba完成支付后，系统会使用您在配置文件中设置的GUHEMBA_REDIRECT_URL值将其重定向回您的系统。

现在，要获取他执行的交易信息，请使用以下脚本：

    function guhembaCallback()
    {
        $transaction = Guhemba::transaction()->getTransaction();
    }

对于无状态，您可以按照以下方式获取交易信息：

    function guhembaCallback()
    {
        $transaction = Guhemba::stateless()->transaction()->getTransaction();
    }

这次，将在交易object上添加一个额外的字段：reference。

6.2 使用交易令牌获取交易信息

可能需要检查具有给定令牌的支付交易是否存在于您的guhemba商家钱包中，为此您只需要以下脚本：

  $token = 'S-7578987654';

  $transaction = Guhemba::transactionFromToken(
                    $token
                )->getTransaction();

6.3 使用支付参考获取交易信息

您可能需要检查您已启动的交易发生了什么，但您没有交易令牌，该软件包提供了一种使用您在生成二维码时提供的支付参考进行检查的方法。

    $paymentRef = "2";
    $paymentConfirmKey = "09876545";
    $response = Guhemba::transactionFromPaymentReference(
        $paymentRef,
        $paymentConfirmKey
    );

    if (!$response->isOk()) dd($response->getMessage());

    $transaction = $response->getTransaction();

注意：$paymentConfirmKey是可选的，但如果您在不同电子商务网站上使用您的商家钱包，它对于精确获取结果非常重要。

6.3 使用二维码ID获取交易信息

您也可以使用您生成的支付二维码ID来检查交易是否存在。

    $qrcodeId = 4;
    $response = Guhemba::transactionFromQrcode(
        $qrcodeId
    );

    if (!$response->isOk()) dd($response->getMessage());

    $transaction = $response->getTransaction();

7. 需要特别使用的其他方法，特别是用于错误处理

7.1 getResponse()

您可以在所有请求上调用此方法，除了redirect方法。例如，您想要生成一个二维码：

    $amount = 1000;
    $response = Guhemba::generateQrcode($amount)->getResponse();

上述脚本将为您提供包含所有响应属性的对象。

7.1 isOk() 和 getMessage()

为了检查请求是否成功执行，您可以使用isOk方法以避免系统中的错误。也可能发生请求没有成功执行的情况，此时您将需要使用getMessage()方法。

    $amount = 1000;
    $generateQrcode = Guhemba::generateQrcode($amount);

    if (! $generateQrcode->isOk()) return $generateQrcode->getMessage();

    $qrcode = $generateQrcode->getQrcode();

注意：isOkay方法是一个布尔值，而getMessage()返回一个字符串。

祝大家享受。

rwbuild / guhemba-web-element

维护者

详细信息