njoguamos/laravel-jenga

用于设置和交互Jenga V3 API的Laravel包。

维护者

详细信息

github.com/njoguamos/laravel-jenga

主页

源代码

问题

安装: 60

依赖项: 0

建议者: 0

安全性: 0

星级: 7

关注者: 1

分支: 1

公开问题: 0

v1.7.1 2024-04-15 20:48 UTC

Requires

Requires (Dev)

MIT 49f56ea1e50f4bfccc89b2170d250c1b132b2ba1

  • Njogu Amos <njoguamos.woop@gmail.com>

laravelpayment gatewayequity bankJenga APINjogu AmosJenga V3 API

This package is auto-updated.

Last update: 2024-09-15 21:46:18 UTC

README

Cover

Laravel 9+ 的 Jenga API 包装器

run-tests License Latest Stable Version Issues Total Downloads

1. 使用此包的原因

  1. 在给定时间段后（例如每15分钟）生成 jenga api access_token 的一种方式
  2. 提供一种流畅的生成 jenga api 密钥对的 private key 和 public key 的方式
  3. 自动生成 jenga api Bearer Token
  4. 提供与 Jenga API 交互的无缝网关

信息 准备开始吗？我已经准备了一个 沙箱，您可以克隆并开始使用。它将帮助您测试凭据，同时向您展示如何将此包与您的 Laravel 应用程序集成。

2. 文档

2.1 安装

使用 Composer 包管理器将此包安装到您的 Laravel 项目中

composer require njoguamos/laravel-jenga

2.2 更新 .env 变量

此包假定您有一个 JengaHQ 账户，并且您有来自 Jenga 的 Api Key、Merchant Code 和 Consumer Secret（https://developer.jengaapi.io/docs/developer-quickstart）。

复制相应的密钥并将它们放置在以下示例中。

JENGA_LIVE_MODE=false
JENGA_MERCHANT_CODE=
JENGA_API_KEY=
JENGA_CONSUMER_SECRET=

# Optional
JENGA_DEFAULT_ACC=
JENGA_DEFAULT_WALLET=
JENGA_COUNTRY_CODE=

注意 对于 JENGA_LIVE_MODE，在测试时使用 false，在运行实时交易时使用 true

2.3 初始化包

您必须运行安装命令，该命令将发布 jenga.php 配置文件和 create_jenga_tokens 迁移

php artisan jenga:install

注意 由于安全原因，access_token 和 refresh_token 将使用您的 application key 进行加密。您可以从 Laravel 文档 中了解有关加密的更多信息

您现在可以迁移数据库了。

php artisan migrate

2.4 生成 Bearer Token

一旦您有有效的凭据，请运行以下命令。

php artisan jenga:auth

此命令将从 Jenga API 获取 access_token 令牌并将其添加到 jenga 表中的新记录。

此命令可能会失败

  • 当您未连接到互联网时
  • 当 Api Key 或 Consumer Secret 或 Merchant 无效时
  • Jenga API 端点存在问题

2.5 生成 Bearer Token 频繁

生成的 access_token 在特定时间段后过期，通常在 一小时 后。要自动生成新的 access_token，请在控制台内核中安排 jenga:auth 命令。安排的时间应少于 15 分钟。

// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    # ...
    $schedule->command(command: 'jenga:auth')->everyThirtyMinutes();
}

2.6 清除过期令牌

为了定期删除过期的 Bearer Token，请在控制台内核中安排 model:prune 命令。

// app/Console/Kernel.php

use NjoguAmos\Jenga\Models\JengaToken;
 
protected function schedule(Schedule $schedule)
{
    # ...
     $schedule->command(command: 'model:prune', parameters: [
        '--model' => [JengaToken::class],
    ])->everyFiveMinutes();
}

2.7 生成私钥和公钥

要生成一对私钥和公钥，请运行以下命令。

php artisan jenga:keys

此命令将在您的 Laravel 应用程序存储文件夹中创建 jenga.key 和 jenga.pub.key 文件。您可以使用 JENGA_KEYS_PATH 变量自定义目录。

# ./yourapplication/storage/jenga.key

-----BEGIN PRIVATE KEY-----
<private key here>
-----END RSA PRIVATE KEY-----

# ./yourapplication/storage/jenga.pub.key

-----BEGIN PUBLIC KEY-----
<public key here>
-----END PUBLIC KEY-----

您可以使用 --force 标志替换现有密钥。默认密钥大小为 4096

警告 生成的密钥文件 绝对不应该 存储在源代码管理中。请确保您将它们添加到您的 gitignore 文件中。

注意 在生成密钥时，需要使用 bcmath、gmp、libsodium 和 openssl 等扩展。

2.8 确保您已订阅API服务

如果您尝试访问API并收到“未授权访问API”的提示，请确认您的账户已订阅您尝试访问的服务。您可以通过前往JengaAPI设置 -> 订阅，然后进行 subscribe 或 unsubscribe 来完成此操作。

3. 使用方法

3.1 生成签名

要手动生成签名，请使用您要签名的数据调用`JengaSignature`类中的`getSignature`方法。

信息 数据将按照传递的顺序进行签名。

use NjoguAmos\Jenga\JengaSignature;

$data = [
    "accountId"   => "0011547896523",
    "countryCode" => "KE",
    "date"        => "2022-01-01"
];

$signature = (new JengaSignature(data: $data))->getSignature();
// This will return signature for "0011547896523KE2022-01-01'
// "NCgbapJwPIt+203eyADfPSvPX6uWPPVwMbFdrW+3XoT7oQC2+IaS6srFIGGdMrwrTH ..."

3.2 支付网关结账

要使用支付网关，请使用后端准备数据并将其传递到浏览器表单。 
<?php
use NjoguAmos\Jenga\Models\JengaToken;

return view(view: 'check-out', data: [
    'token' => JengaToken::query()->latest()->first()?->access_token, // Token generated via auth API
    'checkOutUrl' => config(key: 'jenga.checkout'), // Check our url. Don't modify
    'merchantCode' => config(key: 'jenga.merchant'), // The merchant code provided at registration.
    'wallet' => config(key: 'jenga.wallet'), // The wallet to be used for the transaction
    'orderAmount' => '', // The value of the transaction
    'orderReference' => '', // The merchant order reference. Min8 characters and It has to be alphanumeric
    'productType' => '', // Product category
    'productDescription' => '' // A brief summary of the product. Max 200 characters. Alphanumeric only., 
    'customerFirstName' => '', // The customer's First Name
    'customerLastName' => '', // The customer's Last Name
    'customerEmail' => '', // Customer email
    'customerPhone' => '', // Customer phone number e.g 700325008
    'countryCode' => config(key: 'jenga.country'), // Country code
    'customerPostalCodeZip' => '', // Customer’s postal code
    'customerAddress' => '', // Customer’s address
    'callbackUrl' => '' // Merchant callback url
    'extraData' => '', // This data will be echoed back during callback url
]);

配置您的前端表单。

<form id="submitcheckout" action="{{ $checkOutUrl }}" method="POST">
    @csrf
    
    <input type="hidden" id="token" name="token" value="{{ $token }}">
    <input type="hidden" id="merchantCode" name="merchantCode" value="{{ $merchantCode }}">
    <input type="hidden" id="wallet" name="wallet" value="{{ $wallet }}">
    <input type="hidden" id="orderAmount" name="orderAmount" autofocus value="{{ $orderAmount }}">
    <input type="hidden" id="orderReference" name="orderReference" value="{{ $orderReference }}">
    <input type="hidden" id="productType" name="productType" value="{{ $productType }}">
    <input type="hidden" id="productDescription" name="productDescription" value="{{ $productDescription }}">
    <input type="hidden" id="customerFirstName" name="customerFirstName" value="{{ $customerFirstName }}">
    <input type="hidden" id="customerLastName" name="customerLastName" value="{{ $customerLastName }}">
    <input type="hidden" id="customerEmail" name="customerEmail" value="{{ $customerEmail }}">
    <input type="hidden" id="customerPhone" name="customerPhone" value="{{ $customerPhone }}">
    <input type="hidden" id="countryCode" name="countryCode" value="{{ $countryCode }}">
    <input type="hidden" id="customerPostalCodeZip" name="customerPostalCodeZip" value="{{ $customerPostalCodeZip }}">
    <input type="hidden" id="customerAddress" name="customerAddress" value="{{ $customerAddress }}">
    <input type="hidden" id="callbackUrl" name="callbackUrl" value="{{ $callbackUrl }}">
    <input type="hidden" id="extraData" name="extraData" value="{{ $extraData }}">

    <button type="submit">Subscribe</button>
</form>

成功的响应应如下所示。

{
    "responseStatus": "true",
    "transactionStatus": "SUCCESS",
    "orderReference": "226151",
    "extraData": "pmQgkBuepzSaiNdRh1rghq2ldPzdq0gQ",
    "transactionReference": "RBF2PJILMC",
    "transactionDate": "Wed Feb 15 2023",
    "transactionAmount": "1",
    "transactionCurrency": "KES",
    "message": "Transaction completed successfully",
    "paymentChannel": "MOBILE",
    "orderItems": "undefined",
    "secureResponse": "320396408033f540f6c9bcc426d6e3d1206d584984d72da4017cace6337e4e10d1729ed98ee326d5d0c403c298c789a9YhubIYK7B+WE0Bij2XWxn3iOL+MAyfWU3RruohGTfdB9t5j9lmNTqcmIeY8RL5M\/xenV+hIKvdweVIyzqX333PFgFGd4wV3+LwQpx9LGCxDsj0NFC+ouRdFZ0VADWbnCbZbHlBSO8kxIP8urAXuP1JM21DhTPqzbs8TB763IYmqVHCicmalkDdegDwo+BDQ0HJaf0ia3FektL2v\/Hj3nM9RkmNyA59VH0p5gUhRUhioMxNdFjai9TKZ3CwOZ6O75h5sc7L+Z8w3ucpvYOtuaTV5fxKIfSPkfi3mIvuGQEw7QDJeu3333BRDHt3XobtxZv9GW9\/eey1dRnNW9zplMBxQupJAn98fSKSC0VkSByqt5KKibQFAZxCOYjcvIJ0kea8MkBRwA\/z1YRdeQ+TmQmdLFoe3V3jWyE5SsN6EPU4k="
}

客户也应收到如下短信。

Your transaction of Kshs.  1.00  has successfully been 
credited to Finserve Africa Limited-E Commerce Collection 
Account with Ref. Number  INVDRT and MPESA Tran Ref 
RBF2PJILMC. Thank you

3.3 账户服务

  • 账户余额
  • 账户MINI对账单
  • 账户完整对账单
  • 开户和结账账户余额
3.3.5 账户查询 - 银行账户

要获取账户详情，请调用 AccountInquiry 并传入账户号码和国家代码。如果没有传递参数，将使用在 配置 中配置的默认账户和国家。

use NjoguAmos\Jenga\Api\AccountInquiry;

$search = (new AccountInquiry())
    ->search(
        countryCode: $data['countryCode'],
        accountNumber: $data['accountNumber']
    );

响应应如下所示

{
    "status": true,
    "code": 0,
    "message": "success",
    "data": {
        "account": {
            "branchCode": "145",
            "number": "1450160649886",
            "currency": "KES",
            "status": "Active"
        },
        "customer": [
            {
                "name": "CATHERINE MURANDITSI MUKABWA",
                "id": "54307789658",
                "type": "Retail"
            }
        ]
    }
}

3.4 发送资金

  • 在Equity Bank内
  • 到移动钱包
  • 实时全额结算 (RTGS)
  • 环球银行金融电信协会 (SWIFT)
  • Pesalink - 到银行账户
  • Pesalink - 到手机号码

3.5 发送资金 - IMT

  • IMT 在Equity Bank内
  • IMT 到移动钱包
  • IMT Pesalink - 到银行账户
  • IMT Pesalink - 到银行手机

3.6 接收资金

  • 接收支付 - 账单支付
  • 接收支付 - 商户支付
  • 账单验证

3.6 接收资金查询

  • 获取所有EazzyPay商户
  • 查询交易详情
  • 获取所有账单方

3.8 充值话费

  • 购买话费

3.9 汇率

获取Equity Bank对主要货币的每日货币兑换率。 
use NjoguAmos\Jenga\Api\ForexExchangeRates;
use NjoguAmos\Jenga\Dto\ExchangeRatesDto;

// Convert 1042 USD into KES using Equity Bank Kenya rate.
$data = new ExchangeRatesDto(
    amount: 1042,
    currencyCode: "USD",
    toCurrency: "KES",
    accountNumber: '1450160649886',
    countryCode: 'KE'
);

$rates = (new ForexExchangeRates())->convert($data);

示例成功响应

{
    "status": true,
    "code": 0,
    "message": "success",
    "data": {
      "convertedAmount": 127749.2,
      "rate": 122.6,
      "fromAmount": 1042,
      "rateCode": "TTB"
    }
  }

请参阅外汇API参考

支持货币

3.10 身份搜索与验证

查询东非各国各种人员注册机构。 
use NjoguAmos\Jenga\Api\IDVerification;
use NjoguAmos\Jenga\Dto\IDVerificationDto;

$data = new IDVerificationDto(
    documentNumber: '555555',
    firstName: 'John',
    lastName: 'Doe',
    dateOfBirth: '20 June 1985',
    documentType: 'ID',
    countryCode: 'KE',
);

$search = (new IDVerification())->search($data);

示例成功响应

{
    "status": true,
    "code": 0,
    "message": "success",
    "data": {
        "identity": {
            "customer": {
                "firstName": "JOHN",
                "lastName": "DOE",
                "occupation": "",
                "gender": "M",
                "nationality": "Kenyan",
                "deathDate": "",
                "fullName": "JOHN JOHN DOE DOE",
                "middlename": "JOHN DOE",
                "ShortName": "JOHN",
                "birthCityName": "",
                "birthDate": "1985-06-20T12:00:00",
                "faceImage": ""
            },
            "documentType": "NATIONAL ID",
            "documentNumber": "555555",
            "documentSerialNumber": "55555555555",
            "documentIssueDate": "2011-12-08T12:00:00",
            "documentExpirationDate": "",
            "IssuedBy": "REPUBLIC OF KENYA",
            "additionalIdentityDetails": [
                {
                    "documentType": "",
                    "documentNumber": "",
                    "issuedBy": ""
                }
            ],
            "address": {
                "locationName": "",
                "districtName": "",
                "subLocationName": "",
                "provinceName": "",
                "villageName": ""
            }
        }
    }
}

请参阅ID搜索与验证API参考

3.11 MPGS直接集成

  • MPGS验证支付
  • MPGS验证支付
  • MPGS授权支付
  • MPGS查询支付
  • MPGS退款支付

4. 测试

composer test

5. 更新日志

请参阅RELEASES 获取更多信息。

6. 贡献

请参阅CONTRIBUTING 获取详细信息。

7. 安全

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

8. 致谢

9. 许可证

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