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

结账是我们可以开始处理支付的 simplest Selcom API。

使用 USSD 进行结账支付

此 API 在调用后自动拉取您的用户的 USSD 支付菜单。

注意：目前，此功能仅适用于 AirtelMoney 和 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 结账，并使用以下其他结账选项中的令牌。

结账到支付页面（无卡片）

支付页面包含 QR 码、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"

对于 JSON 请求（API 应用），此类结账到支付页面的返回数据将包含 payment_gateway_url，而不是重定向到该页面

{
  "payment_gateway_url": "https://example.selcommobile-url.com"
}

使用卡片进行结账支付（不导航到支付页面）

要使用卡片而不导航到支付页面，您需要已通过导航到支付页面为付款用户创建了一张卡片。

这对于周期性或按需的卡支付非常有用。数据与之前的卡结账相同，只是我们增加了 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);

bryceandy / laravel-selcom

维护者

详细信息