README

Selcom 包用于 Laravel 应用程序

此包允许 Laravel 开发者将他们的网站/API 与所有 Selcom API 服务集成

安装

预安装要求

支持从版本 8.* 开始的 Laravel 项目
最低 PHP 版本是 7.4
您的服务器必须已安装 cURL PHP 扩展（ext-curl）

然后继续安装

composer require bryceandy/laravel-selcom

配置

要访问 Selcom 的 API，您需要向包提供访问您 Selcom vendorID、API 密钥和密钥的权限。

从 Selcom 支持获得这三个凭证后，在 .env 变量中添加它们的值

SELCOM_VENDOR_ID=123456
SELCOM_API_KEY=yourApiKey
SELCOM_API_SECRET=yourSecretKey

SELCOM_IS_LIVE=false

注意：开始时，您将获得测试凭证。

当您切换到实时凭证时，不要忘记将 SELCOM_IS_LIVE 更改为 true。

我们将随着进程的进行更新更多配置设置，但您可以随时发布配置以完全自定义它。

php artisan vendor:publish --tag=selcom-config

运行迁移命令以创建一个存储 Selcom 付款的表

php artisan migrate

结账 API

结账是我们可以开始处理付款的最简单的 Selcom API。

使用 USSD 进行结账付款

此 API 会在被调用后自动提取用户的 USSD 付款菜单。

注意：目前，此功能仅适用于 AitelMoney 和 TigoPesa 用户。

use Bryceandy\Selcom\Facades\Selcom;

Selcom::checkout([
    'name' => "Buyer's full name", 
    'email' => "Buyer's email",
    'phone' => "Buyer's msisdn, for example 255756334000",
    'amount' => "Amount to be paid",
    'transaction_id' => "Unique transaction id",
    'no_redirection' => true,
    // Optional fields
    'currency' => 'Default is TZS',
    'items' => 'Number of items purchased, default is 1',
    'payment_phone' => 'The number that will make the USSD transactions, if not specified it will use the phone value',
]);

其他网络可能需要手动使用 USSD 结账，如以下其他结账选项中所示。

跳转到付款页面（不使用卡片）

付款页面包含二维码、Masterpass、USSD 钱包提取、带有令牌的移动货币付款等付款选项。

要跳转到此页面，我们将使用之前的示例，但返回时不带 no_redirection 选项或将其赋值为 false

use Bryceandy\Selcom\Facades\Selcom;

return Selcom::checkout([
    'name' => "Buyer's full name", 
    'email' => "Buyer's email",
    'phone' => "Buyer's msisdn, for example 255756334000",
    'amount' => "Amount to be paid",
    'transaction_id' => "Unique transaction id",
]);

跳转到付款页面（使用卡片）

要使用付款页面上的卡片，返回以下请求

use Bryceandy\Selcom\Facades\Selcom;

return Selcom::cardCheckout([
    'name' => "Buyer's full name", 
    'email' => "Buyer's email",
    'phone' => "Buyer's msisdn, for example 255756334000",
    'amount' => "Amount to be paid",
    'transaction_id' => "Unique transaction id",
    'address' => "Your buyer's address",
    'postcode' => "Your buyer's postcode",
    // Optional fields
    'user_id' => "Buyer's user ID in your system",
    'buyer_uuid' => $buyerUuid, // Important if the user has to see their saved cards.
    // See the last checkout section on how to fetch a buyer's UUID
    'country_code' => "Your buyer's ISO country code: Default is TZ",
    'state' => "Your buyer's state: Default is Dar Es Salaam",
    'city' => "Your buyer's city: Default is Dar Es Salaam",
    'billing_phone' => "Your buyer's billing phone number: forexample 255756334000",
    'currency' => 'Default is TZS',
    'items' => 'Number of items purchased, default is 1',
]);

可选地，您可以通过 .env 文件指定以下内容

用户完成付款后将被重定向到的页面

SELCOM_REDIRECT_URL=https://mysite.com/selcom/redirect

用户取消付款流程时将被带到页面

SELCOM_CANCEL_URL=https://mysite.com/selcom/cancel

如果您觉得麻烦，此包已为您提供了这些页面。如果您想自定义它们，请运行

php artisan vendor:publish --tag=selcom-views

此外，您可以为包分配一个前缀。这将应用于路由和订单 ID

SELCOM_PREFIX=SHOP

自定义付款页面主题

配置包含一个指定付款页面主题的 colors 字段。

要自定义颜色，请在 .env 文件中添加颜色值

SELCOM_HEADER_COLOR="#FG345O"
SELCOM_LINK_COLOR="#000000"
SELCOM_BUTTON_COLOR="#E244FF"

使用卡片进行结账付款（不跳转到付款页面）

要使用卡片而不跳转到付款页面，您需要通过跳转到付款页面来为付款用户创建一张卡片。

这对于定期或按需卡付款非常有用。数据与之前的卡结账相同，但我们添加了 no_redirection、user_id & buyer_uuid

use Bryceandy\Selcom\Facades\Selcom;

Selcom::cardCheckout([
    'name' => "Buyer's full name", 
    'email' => "Buyer's email",
    'phone' => "Buyer's msisdn, for example 255756334000",
    'amount' => "Amount to be paid",
    'transaction_id' => "Unique transaction id",
    'no_redirection' => true,
    'user_id' => "Buyer's user ID in your system",
    'buyer_uuid' => $buyerUuid, // See instructions below on how to obtain this value
    'address' => "Your buyer's address",
    'postcode' => "Your buyer's postcode",
    // Optional fields
    'country_code' => "Your buyer's ISO country code: Default is TZ",
    'state' => "Your buyer's state: Default is Dar Es Salaam",
    'city' => "Your buyer's city: Default is Dar Es Salaam",
    'billing_phone' => "Your buyer's billing phone number: forexample 255756334000",
    'currency' => 'Default is TZS',
    'items' => 'Number of items purchased, default is 1',
]);

此方法将获取用户的 3 张已保存卡片并尝试所有卡片，直到付款成功或全部失败。

获取买家的 UUID

如果该用户之前访问过支付页面进行支付，则其uuid已经在数据库中。

use Illuminate\Support\Facades\DB;

$buyerUuid = DB::table('selcom_payments')
    ->where([
        ['user_id', '=' auth()->id()],
        ['gateway_buyer_uuid', '<>', null],
    ])
    ->value('gateway_buyer_uuid');

列出用户的存储卡片

获取用户的存储卡片可以用来了解用户是否有卡片，或者是否有删除的必要。

您需要用户的ID和buyer_uuid

use Bryceandy\Selcom\Facades\Selcom;

Selcom::fetchCards($userId, $gatewayBuyerUuid);

删除用户的存储卡片

要删除用户的存储卡片，您需要一个buyer_uuid和从上述fetchCards请求中获得的卡片ID。

use Bryceandy\Selcom\Facades\Selcom;

Selcom::deleteCard($cardId, $gatewayBuyerUuid);

结账webhook/callback

该软件包包含支付webhook的实现。

当Selcom将支付状态发送到您的网站时，selcom_payments表中的数据将被更新，并触发一个事件Bryceandy\Selcom\Events\CheckoutWebhookReceived。

您可以创建一个事件监听器

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        \Bryceandy\Selcom\Events\CheckoutWebhookReceived::class => [
            \App\Listeners\ProcessWebhook::class,
        ],
    ];
}

然后在您的监听器App\Listeners\ProcessWebhook中，您可以对订单ID进行任何操作

<?php

namespace App\Listeners;

use Bryceandy\Selcom\Events\CheckoutWebhookReceived;
use Bryceandy\Selcom\Facades\Selcom;
use Illuminate\Support\Facades\DB;

class ProcessWebhook
{
    /**
     * Handle the event.
     *
     * @param CheckoutWebhookReceived $event
     */
    public function handle(CheckoutWebhookReceived $event)
    {
        // Get the order id
        $orderId = $event->orderId;
        
        // Fetch updated record in the database, and do what you need with it
        $status = DB::table('selcom_payments')
            ->where('order_id', $orderId)
            ->value('payment_status');
        
        if ($status === 'PENDING') {
            Selcom::orderStatus($orderId); // Or dispatch a job minutes later to query order status
        }
    }
}

检查订单状态

要查询订单状态到Selcom，只需运行

use Bryceandy\Selcom\Facades\Selcom;
use Illuminate\Support\Facades\DB;

$order = Selcom::orderStatus($orderId);

一旦您获得了订单数据，您可以按自己的意愿使用它。以下示例更新数据库中的支付

DB::table('selcom_payments')->where('order_id', $orderId)
    ->update(array_merge(
        'payment_status' => $order['payment_status'],
        ($order['payment_status'] === 'COMPLETED'
            ? [
                'selcom_transaction_id' => $order['transid'],
                'channel' => $order['channel'],
                'reference' => $order['reference'],
                'msisdn' => $order['msisdn'],
            ]
            : []
        )
    ));

列出订单

要列出所有发送到Selcom的订单，只需指定from_date和to_date

use Bryceandy\Selcom\Facades\Selcom;

$fromDate = '2021-02-16';
$toDate = '2021-12-25';

Selcom::listOrders($fromDate, $toDate);

取消订单

要取消Selcom订单，只需运行

use Bryceandy\Selcom\Facades\Selcom;

Selcom::cancelOrder($orderId);

robertkonga / laravel-selcom-master

维护者

详细信息