README

Paystack 的 PHP API 包装器 Paystack。

要求

Curl 7.34.0 或更高版本（除非使用 Guzzle）
PHP 5.4.0 或更高版本
OpenSSL v1.0.1 或更高版本

安装

通过 Composer

    $ composer require yabacon/paystack-php

通过下载

从发布页面下载一个版本。解压后

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

重要

版本 2 与版本 1 的代码不兼容！如果 cURL 出现问题或 Paystack API 响应体中的状态为错误，则会引发错误。

使用方法

将重定向到从交易/初始化端点接收的授权 URL。此 URL 只使用一次，因此请确保每个交易生成一个新的 URL。

当支付成功时，我们将调用您的回调 URL（在您的仪表板中设置或在初始化交易时设置）并返回第一步中发送的参考作为查询参数。

如果您使用测试密钥，我们将调用您的测试回调 URL，否则我们将调用您的实时回调 URL。

0. 前提条件

确认您的服务器可以与 Paystack 的服务器建立 TLSv1.2 连接。大多数最新的软件都具备此功能。如果您有任何 SSL 错误，请联系您的服务提供商以获取指导。不要禁用 SSL 对等验证！

1. 准备您的参数

email 和 amount 是最常见的必填参数。请为每位客户发送唯一的电子邮件。如果您的客户没有提供唯一的电子邮件，请制定策略为每个客户设置一个。以下任何一种方法都适用。我们接受的所有端点的金额都以科博为单位，必须是整数。例如，要接受 456 奈拉，78 科博，请发送 45678 作为金额。

2. 初始化交易

通过调用我们的 API 来初始化交易。

    $paystack = new Yabacon\Paystack(SECRET_KEY);
    try
    {
      $tranx = $paystack->transaction->initialize([
        'amount'=>$amount,       // in kobo
        'email'=>$email,         // unique to customers
        'reference'=>$reference, // unique to transactions
      ]);
    } catch(\Yabacon\Paystack\Exception\ApiException $e){
      print_r($e->getResponseObject());
      die($e->getMessage());
    }

    // store transaction reference so we can query in case user never comes back
    // perhaps due to network issue
    save_last_transaction_reference($tranx->data->reference);

    // redirect to page so User can pay
    header('Location: ' . $tranx->data->authorization_url);

当用户输入其卡详细信息时，Paystack 将验证并扣款。它将执行以下所有操作

返回到在初始化交易时设置的或您的仪表板上的回调 URL：https://dashboard.paystack.co/#/settings/developer 。如果两者都没有设置，客户将看到“交易成功”的消息。

向您的 Webhook URL 发送 charge.success 事件，该 URL 设置在：https://dashboard.paystack.co/#/settings/developer

如果未关闭收据，将向客户的电子邮件发送 HTML 收据。

在向客户付款之前，请通过我们的验证端点进行服务器端调用，以确认交易的状态和属性。

3. 处理 charge.success 事件

我们将向为您的交易域名设置的 Webhook URL 发送 charge.success 事件。如果是实时交易，我们将向您的实时 Webhook URL 发送，反之亦然。

如果使用 .htaccess，请记住将尾随斜杠添加到您设置的 URL。
向您的 URL 进行测试 POST，并确保脚本获取到 POST 正文。
公开可用的URL（https:// 无法接收！）

    // Retrieve the request's body and parse it as JSON
    $event = Yabacon\Paystack\Event::capture();
    http_response_code(200);

    /* It is a important to log all events received. Add code *
     * here to log the signature and body to db or file       */
    openlog('MyPaystackEvents', LOG_CONS | LOG_NDELAY | LOG_PID, LOG_USER | LOG_PERROR);
    syslog(LOG_INFO, $event->raw);
    closelog();

    /* Verify that the signature matches one of your keys*/
    $my_keys = [
                'live'=>'sk_live_blah',
                'test'=>'sk_test_blah',
              ];
    $owner = $event->discoverOwner($my_keys);
    if(!$owner){
        // None of the keys matched the event's signature
        die();
    }

    // Do something with $event->obj
    // Give value to your customer but don't give any output
    // Remember that this is a call from Paystack's servers and
    // Your customer is not seeing the response here at all
    switch($event->obj->event){
        // charge.success
        case 'charge.success':
            if('success' === $event->obj->data->status){
                // TIP: you may still verify the transaction
                // via an API call before giving value.
            }
            break;
    }

4. 验证交易

在我们将您重定向到回调URL后，请在给予价值之前验证交易。

    $reference = isset($_GET['reference']) ? $_GET['reference'] : '';
    if(!$reference){
      die('No reference supplied');
    }

    // initiate the Library's Paystack Object
    $paystack = new Yabacon\Paystack(SECRET_KEY);
    try
    {
      // verify using the library
      $tranx = $paystack->transaction->verify([
        'reference'=>$reference, // unique to transactions
      ]);
    } catch(\Yabacon\Paystack\Exception\ApiException $e){
      print_r($e->getResponseObject());
      die($e->getMessage());
    }

    if ('success' === $tranx->data->status) {
      // transaction was successful...
      // please check other things like whether you already gave value for this ref
      // if the email matches the customer who owns the product etc
      // Give value
    }

5. 结束语

通常，在构建Paystack对象后进行API请求，通过调用资源/方法如下： $paystack->{resource}->{method}()；对于GET操作，使用$paystack->{resource}(id)，要列出资源：使用$paystack->{resource}s()。

目前，我们支持：'customer', 'page', 'plan', 'subscription', 'transaction' 和 'subaccount'。请查看我们的API参考（link-paystack-api-reference），了解支持的方法。要指定参数，请发送为数组。

查看SAMPLES以获取更多示例调用

额外内容

有一些类可以帮助开发者完成在Paystack上经常需要执行的一些任务

费用

此类与金额和您的Paystack费用一起工作。使用时，创建一个新的Fee对象

    $fee = new Yabacon\Paystack\Fee();

配置它

    $fee->withPercentage(0.015);        // 1.5%
    $fee->withAdditionalCharge(10000);  // plus 100 NGN
    $fee->withThreshold(250000);        // when total is above 2,500 NGN
    $fee->withCap(200000);              // capped at 2000

计算费用

    $chargeOn300naira = $fee->calculateFor(30000);
    $chargeOn7000naira = $fee->calculateFor(700000);

了解当您想要结算特定金额时，应该向API发送什么内容

    $iWant100Naira = $fee->addFor(10000);
    $iWant4000Naira = $fee->addFor(400000);

事件

此类帮助您捕获和我们的事件

    $event = Yabacon\Paystack\Event::capture();

通过密钥验证它

    if($event->validFor($mySecretKey))
    {
        // awesome
    }

发现拥有它的密钥（在同一个webhook接收多个集成的情况下）。这对于多租户系统很有用。或者简单地如果您想有相同的测试和生产webhook URL。

    $my_keys = [
                'live'=>'sk_live_blah',
                'test'=>'sk_test_blah',
              ];
    $owner = $event->discoverOwner($my_keys);
    if(!$owner){
        // None of my keys matched the event's signature
        die();
    }

将事件转发到另一个URL。如果您想使其他系统通知相同的精确事件。

    $evt->forwardTo('http://another-webhook.url');

MetadataBuilder

此类帮助您构建有效的JSON元数据字符串，以便在发出交易请求时发送。

    $builder = new MetadataBuilder();

添加元数据

通过调用withKeyName魔法函数添加元数据（这些将不会显示在仪表板上）。不要使用CustomFields作为键名

    $builder->withQuoteId(10); // will add as quote_id: 10 unless you turn auto_snake_case off
    $builder->withMobileNumber(08012345678); // will add as mobile_number: 08012345678
    $builder->withCSRF('dontacceptpaymentunlessthismatches');

要关闭键名的自动蛇形命名，请执行以下操作：

    MetadataBuilder::$auto_snake_case = false;

在您开始向$builder添加元数据之前。

添加自定义字段

通过调用withCustomField函数添加自定义字段（这些将显示在仪表板上）。

    $builder->withCustomField('Mobile Number', '080123456789');
    $builder->withCustomField('See Me', 'I\'m Visible on your Dashboard');

构建JSON

最后调用build()以获取您的JSON元数据字符串。

使用自定义路由

您可以通过在paystack对象上调用useRoutes方法来添加您的自定义路由。

    $paystack = new Yabacon\Paystack(SECRET_KEY);
    $paystack->useRoutes(["charge" => Charge::class]);

    $paystack->charge->chargeMobileMoney([
          'email' => 'hey@example.com',
          'reference' => 'trnx_ref',
          'amount' => 50 * 100,
          'currency' => 'GHS',
          'mobile_money' => [
            'phone' => '5533467',
            'provider' => 'MTN'
          ]
    ]);

您的自定义路由应实现Yabacon\Paystack\Contracts\RouteInterface合约

    class Charge implements RouteInterface
    {

        public static function root()
        {
            return '/charge';
        }

        public static function chargeMobileMoney()
        {
            return [
                RouteInterface::METHOD_KEY => RouteInterface::POST_METHOD,
                RouteInterface::ENDPOINT_KEY => Charge::root(),
                RouteInterface::PARAMS_KEY => [
                    'email',
                    'reference',
                    'amount',
                    'currency',
                    'mobile_money',
                ],
            ];
        }
    }

变更日志

请参阅CHANGELOG以了解最近发生了什么更改。

测试

    $ composer test

贡献

请参阅CONTRIBUTING 和 CONDUCT 以了解详细信息。检查我们的待办事项列表以了解已计划的功能。

安全性

如果您发现任何安全相关的问题，请通过电子邮件yabacon.valley@gmail.com报告，而不是使用问题跟踪器。

致谢

Yabacon
Issa Jubril
Akachukwu Okafor
Ibrahim Lawal
Opeyemi Obembe - 跟随他在创建NodeJS Wrapper时使用的风格
所有贡献者

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。

yabacon / paystack-php

维护者

详细信息