README

TXTGHANA支付网关PHP SDK _{^{可用于您喜欢的框架或您的纯PHP项目。}}

🔥弃用

如果您是第一次使用此包，我们建议使用其继任者，您可以在这里找到。

为什么？

随着TxtPay更名为Sevotransact，一些事情发生了变化，我们决定创建一个新的包，该包与这个包具有相同的理念。

但我已经在使用这个了！

如果您已经使用此包且无法切换到新版本，请不要担心。我们仍将维护此包（尽管我们会很高兴您切换）。

安装

可以通过composer安装此包。如果您还没有安装，请先安装它。然后在项目根目录下打开一个终端并运行

composer require prinx/txtpay

用法

首先，在项目根目录下创建一个.env文件，如果您还没有的话。

接下来，通过放置txtpay凭证和账户信息来配置.env文件

#...

TXTPAY_ID=your_txtpay_id
TXTPAY_KEY=your_txtpay_key
TXTPAY_ACCOUNT=your_txtpay_account
TXTPAY_NICKNAME=your_txtpay_nickname
TXTPAY_DESCRIPTION=your_txtpay_description
TXTPAY_PRIMARY_CALLBACK=primary_callback
TXTPAY_SECONDARY_CALLBACK=secondary_callback

主要和次要回调是TXTPAY将发送交易结果的URL。您可以在这里检查如何处理交易回调。次要回调是可选的。

请求支付

require 'path/to/vendor/autoload.php'; // Not needed if using a framework.

use Txtpay\MobileMoney;

$payment = new MobileMoney;

$amount = 1; // 1 GHC
$phone = '233...';
$network = 'MTN'; // MTN|AIRTEL|VODAFONE

$request = $payment->request($amount, $phone, $network);

凭证码

某些网络（通常是VODAFONE）要求用户生成一个凭证码。此代码可以轻松传递到请求中

$request = $payment->request($amount, $phone, $network, $voucherCode);

// or

$payment->setVoucherCode($voucherCode);
$request = $payment->request($amount, $phone, $network);

凭证码现在是可选的。如果没有传递，用户将直接在手机上收到提示以接受交易。

移动货币请求响应

移动货币请求将自动返回一个响应，您可以从该响应中确定请求是否正在处理。

$request = $payment->request($amount, $phone, $network);

if ($request->isBeingProcessed()) {
    $status = $request->getStatus();

    // ...
} else {
    $error = $request->getError();

    // ...
}

警告：此响应只是通知您已收到请求并正在处理或发送请求时出现错误。这不是移动货币请求的实际响应。移动货币请求的实际响应将发送到您提供的回调URL。

处理回调

交易结果将发送到请求时提供的回调URL。要处理回调，在您喜欢的框架中创建一个新的路由，或在项目中创建一个php文件来处理回调。解析到该路由或该文件的URL（必须是）在.env中提供的回调URL。

现在您可以创建一个回调实例，它将接收您的交易状态

// File: callback.php

require 'path/to/vendor/autoload.php';

use Txtpay\Callback;

$callback = new Callback;

或者如果您正在使用框架，并且回调路由由控制器处理

// This is just an example.
// Write your controller the way you are used to with your favorite framework.

namespace Controllers;

use Txtpay\Callback;

class MobileMoneyCallbackController extends Controller
{
    public function processCallback()
    {
        $callback = new Callback;
    }
}

我们现在可以注册将在移动货币交易成功、失败或某些定义的特定条件下运行的回调函数。回调函数将接收$callback实例。

$callback->success(function (Callback $callback) {
    // Transaction was successful. Do stuff.
})->failure(function (Callback $callback) {
    // Transaction failed. Do stuff.
})->always(function (Callback $callback) {
    // Do stuff whether transaction was successful or not.
});

您不需要使用所有回调。只需使用您需要的即可。

现在，通过在回调上调用process方法来运行一切。

$callback->process();

完整的代码如下

$callback = new Callback;

$callback->success(function (Callback $callback) {
    //
})->failure(function (Callback $callback) {
    //
})->always(function (Callback $callback) {
    //
})->process();

提示：如果您只有一个回调函数将在交易成功或失败时运行，您可以直接将函数传递到process方法中

$callback = new Callback;

$callback->process(function (Callback $callback) {
    //
});

交易成功

交易代码决定了交易是成功还是失败。默认情况下，成功交易的代码在 $callback->getSuccessCodes() 返回的数组中。您可以决定（无论出于何种原因）将一个失败代码视为成功代码，通过使用 $callback->addSuccessCode($code) 方法将其添加到成功代码中。

on 方法

on 方法是一种强大的监听交易请求回调的方式。它接受第一个参数是一个条件数组，这些条件可以匹配请求的有效负载，第二个参数是当条件与有效负载匹配时将运行的回调函数。

可以将字符串作为条件传递，然后它将被视为传递给回调 URL 的有效负载中的代码。

use Txtpay\Callback;

$callback = new Callback;

$callback->on('000', function (Callback $callback) {
    //
})->on('101', function (Callback $callback) {
    //
})->on(['code' => '000', 'phone' => '233...'], function (Callback $callback) {
    //
})->success(function (Callback $callback){
    // We can still chain the success or failure methods.
})->failure(function (Callback $callback) {
    //
})->process();

回调类实现了 流畅接口。您可以在任何顺序中链式调用大多数方法（如 on、success、failure 方法）。

回调将按照它们注册的顺序执行。

有效负载

有效负载被发送到回调 URL。它包含 8 个参数

code

请求的代码。

$requestCode = $callback->getCode();

status

$requestStatus = $callback->getStatus(); // approved, declined...

details

状态详情信息。

$requestDetails = $callback->getDetails();

id

交易 ID。

$transactionId = $callback->getId();

phone

请求所使用的电话号码。

$phone = $callback->getPhone(); // 233...

network

电话号码所属的网络。

$network = $callback->getNetwork(); // MTN, AIRTEL, VODAFONE, ...

amount

交易金额。

$amount = $callback->getAmount();

currency

交易使用的货币。

$currency = $callback->getCurrency(); // GHS

您可以通过不带参数调用 getPayload 方法来获取所有有效负载数组。

$payload = $callback->getPayload();

您还可以通过将参数名称传递给 getPayload 方法来获取任何有效负载参数，例如

$transactionId = $callback->getPayload('id');
$transactionCode = $callback->getPayload('code');

与请求相关的消息

您可以通过调用回调实例的 message 方法来获取与请求相关的消息。

$message = $callback->getMessage();

消息与有效负载中的代码相关联。

消息

这些是可能的消息

[
    '000'     => 'Transaction successful. Your transaction ID is '.$transactionId,
    '101'     => 'Transaction failed. Insufficient fund in wallet.',
    '102'     => 'Transaction failed. Number non-registered for mobile money.',
    '103'     => 'Transaction failed. Wrong PIN. Transaction timed out.',
    '104'     => 'Transaction failed. Transaction declined',
    '114'     => 'Transaction failed. Invalid voucher',
    '909'     => 'Transaction failed. Duplicate transaction id.',
    'default' => 'Transaction failed.',
];

在闭包中使用移动货币回调实例

回调实例会自动传递给闭包。然后您可以像下面这样做

$callback->success(function (Callback $callback) {
    $message = $callback->getMessage();
});

向闭包传递其他参数

您可以通过在闭包上使用 PHP 的 use 关键字轻松地将其他参数传递给闭包

// SmsService is your own implementation.
$sms = new SmsService();

$callback->success(function (Callback $callback) use ($sms) {
    $message = $callback->getMessage();
    $phone = $callback->getPhone();

    $sms->send($message, $phone);
});

使用类来处理回调

您可以将回调闭包直接传递给 success、failure 或 on 方法，而不是将所有回调移动到一个类中，只需将类传递给 process 方法即可。

首先，创建一个包含 callbacks 方法的类

class CallbackHandler
{
    public function callbacks(Callback $callback)
    {
        //
    }
}

callbacks 方法必须返回一个包含您条件与回调闭包映射的数组

class CallbackHandler
{
    public function callbacks(Callback $callback)
    {
        return [
            ['000', function (Callback $callback) {
                $message = $callback->getMessage();
            }],
            ['101', function (Callback $callback) {
                //
            }],
        ];
    }
}

映射可以重复

class CallbackHandler
{
    public function callbacks(Callback $callback)
    {
        return [
            ['000', function (Callback $callback) {
                //
            }],
            ['000', function (Callback $callback) {
                // Another callback that will be run for the same code.
            }],
            ['101', function (Callback $callback) {
                //
            }],
        ];
    }
}

或者您可以选择传递闭包数组

class CallbackHandler
{
    public function callbacks(Callback $callback)
    {
        return [
            ['000', [
                function (Callback $callback) {
                    //
                },
                function (Callback $callback) {
                    // Another callback that will be run for the same code.
                },
            ]],
            ['101', function (Callback $callback) {
                //
            }],
        ];
    }
}

您可以传递自定义条件 success、failure 或 always

class CallbackHandler
{
    public function callbacks(Callback $callback)
    {
        return [
            ['success', function (Callback $callback) {
                //
            }],
            ['failure', function (Callback $callback) {
                //
            }],
            ['always', function (Callback $callback) {
                //
            }],
        ];
    }
}

您也可以传递条件数组

class CallbackHandler
{
    public function callbacks(Callback $callback)
    {
        return [
            [['code' => '000', 'phone' => '233...'], function (Callback $callback) {
                    //
            }],
        ];
    }
}

所有这些都可以根据您的需要进行混合

class CallbackHandler
{
    public function callbacks(Callback $callback)
    {
        return [
            ['000', function (Callback $callback) {
                //
            }],
            [['code' => '000', 'phone' => '233...'], function (Callback $callback) {
                //
            }],
            ['success', function (Callback $callback) {
                //
            }],
            ['always', function (Callback $callback) {
                //
            }],
        ];
    }
}

您可以在回调处理类中创建公共方法，并在 callbacks 方法中返回的数组中引用这些方法，而不是直接在回调方法中返回闭包

class CallbackHandler
{
    public function callbacks(Callback $callback)
    {
        return [
            ['000', 'sendSms'],
            ['101', ['notifyAdmin', 'sendSms']]
            ['always', 'log'],
        ];
    }

    public function notifyAdmin(Callback $callback)
    {
        // Notify admin...
    }

    public function sendSms(Callback $callback)
    {
        //
    }

    public function log(Callback $callback)
    {
        //
    }
}

编写回调处理类后，只需将其传递给 process 方法即可

// Do not forget to import the class from it namespace
use App\Helpers\CallbackHandler;

$callback = new Callback;

$callback->process(CallbackHandler::class);

日志记录

本地日志记录

您可以提供一个日志文件夹，交易将自动记录到该文件夹。

$callback->setLogFolder($path);

如果没有设置文件夹，则默认日志文件夹将创建在 YOUR_PROJECT_ROOT_FOLDER/storage/logs/txtpay/。

您可以使用环境变量禁用本地日志（默认启用）

TXTPAY_LOCAL_LOG_ENABLED=false

记录到 SLACK

您可以在 .env 文件中提供 Slack webhook，以便自动将交易记录到 Slack。

TXTPAY_SLACK_LOG_WEBHOOK=https://

您可以在 .env 中禁用记录到 SLACK

TXTPAY_SLACK_LOG_ENABLED=false

默认情况下已启用。

禁用日志

要禁用整个日志系统，请在您的 .env 文件中设置

TXTPAY_LOG_ENABLED=false

贡献

星标 ⭐ 仓库，fork 它，修复一个错误，添加一个新功能，编写测试，纠正文档，并提交一个 pull 请求。

许可

MIT