nasrulhazim/billplz

PHP 无关库，用于与 BillPlz API 交互

维护者

详情

github.com/nasrulhazim/billplz

源代码

安装: 41

依赖: 0

建议者: 0

安全性: 0

星标: 1

关注者: 1

分支: 29

v1.1.1 2018-01-07 14:41 UTC

Requires

Requires (Dev)

MIT eed848d79fac8ec87e47c9815d085db14ec230c2

  • Mior Muhammad Zaki <crynobone.woop@gmail.com>

This package is auto-updated.

Last update: 2024-09-06 13:26:21 UTC

README

Build Status Latest Stable Version Total Downloads Latest Unstable Version License

安装

通过 composer 安装，只需在您的 composer.json 文件中放入以下内容

{
    "require": {
        "jomweb/billplz": "^1.0",
        "php-http/guzzle6-adapter": "^1.1"
    }
}

HTTP 适配器

您可能想使用任何其他实现 php-http/client-implementation 的适配器，而不是使用 php-http/guzzle6-adapter。有关 PHP-HTTP 的客户端和适配器，请参阅 客户端 & 适配器。

用法

创建 Billplz 客户端

您可以通过以下代码创建一个 Billplz 客户端（使用 php-http/guzzle6-adapter）

<?php

use Billplz\Client;
use Http\Client\Common\HttpMethodsClient;
use Http\Adapter\Guzzle6\Client as GuzzleHttpClient;
use Http\Message\MessageFactory\GuzzleMessageFactory;

$http = new HttpMethodsClient(
    new GuzzleHttpClient(),
    new GuzzleMessageFactory()
);


$billplz = new Client($http, 'your-api-key');

您也可以使用 php-http/discovery 自动选择通过 composer 安装的适配器

<?php

use Billplz\Client;

$billplz = Client::make('your-api-key');

使用沙箱环境

您可以通过添加以下代码来设置使用开发/沙箱环境

$billplz->useSandbox();

使用不同的 API 版本

默认情况下，jomweb/billplz 将使用 v3 API 版本进行任何请求，但您可以在新 API 版本可用时自定义此设置。

$billplz->useVersion('v4');

创建 Collection 请求

现在您可以创建一个 Collection 实例

$collection = $billplz->collection();

您还可以通过执行 $billplz->collection('v3'); 手动设置 API 版本。您还可以使用 $billplz->resource('Collection'); 来获取相同的结果。

创建 Collection

您可以通过调用以下代码添加新的集合

$response = $collection->create('My First API Collection');

var_dump($response->toArray());
return [
    "id" => "inbmmepb",
    "title" => "My First API Collection",
    "logo" => [
        "thumb_url" => null,
        "avatar_url" => null
    ],
    "split_payment" => [
        "email" => null,
        "fixed_cut" => null,
        "variable_cut" => null
    ]
];

您还可以通过可选参数创建新的集合

$response = $collection->create('My First API Collection', [
    'logo' => '@/Users/Billplz/Documents/uploadPhoto.png',
    'split_payment' => [
        'email' => 'verified@account.com',
        'fixed_cut' => \Money\Money::MYR(100),
    ],
]);

var_dump($response->toArray());
return [
    "id" => "inbmmepb",
    "title" => "My First API Collection",
    "logo" => [
        "thumb_url" => "https://sample.net/assets/uploadPhoto.png",
        "avatar_url" => "https://sample.net/assets/uploadPhoto.png"
    ],
    "split_payment" => [
        "email" => "verified@account.com",
        "fixed_cut" => \Money\Money::MYR(100),
        "variable_cut" => null
    ]
]

创建 Open Collection

$response = $collection->createOpen(
    'My First API Collection',
    'Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst.',
    Money\Money::MYR(299)
);

var_dump($response->toArray());
return [
    "id" => "0pp87t_6",
    "title" => "MY FIRST API OPEN COLLECTION",
    "description" => "Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst.",
    "reference_1_label" => null,
    "reference_2_label" => null,
    "email_link" => null,
    "amount" => \Money\Money::MYR(299),
    "fixed_amount" => true,
    "tax" => null,
    "fixed_quantity" => true,
    "payment_button" => "pay",
    "photo" => [
        "retina_url" =>  null,
        "avatar_url" =>  null
    ],
        "split_payment" => [
        "email" => null,
        "fixed_cut" => null,
        "variable_cut" => null
    ],
    "url" => "https://www.billplz.com/0pp87t_6"
]

创建 Bill 请求

现在您可以创建一个 Bill 实例

$bill = $billplz->bill();

您还可以通过执行 $billplz->bill('v3'); 手动设置 API 版本。您还可以使用 $billplz->resource('Bill'); 来获取相同的结果。

创建 Bill

您可以通过调用以下代码添加新的账单

$response = $bill->create(
    'inbmmepb',
    'api@billplz.com',
    null,
    'Michael API V3',
    Money\Money::MYR(200),
    'http://example.com/webhook/',
    'Maecenas eu placerat ante.'
);

var_dump($response->toArray());
return [
    "id" => "8X0Iyzaw",
    "collection_id" => "inbmmepb",
    "paid" => false,
    "state" => "overdue",
    "amount" => \Money\Money::MYR(200),
    "paid_amount" => \Money\Money::MYR(0),
    "due_at" => \DateTime::createFromFormat('Y-m-d', "2015-3-9"),
    "email" => "api@billplz.com",
    "mobile" => null,
    "name" => "MICHAEL API V3",
    "url" => "https://www.billplz.com/bills/8X0Iyzaw",
    "reference_1_label" => "Reference 1",
    "reference_1" => null,
    "reference_2_label" => "Reference 2",
    "reference_2" => null,
    "redirect_url" => null,
    "callback_url" => "http://example.com/webhook/",
    "description" => "Maecenas eu placerat ante."
];

支付完成

您可以为 Billplz 设置 webhook 以接收 POST 请求。为了接受响应，您只需编写以下内容。

$data = $billplz->webhook($_POST);
return [
    'id' => 'W_79pJDk',
    'collection_id' => 'inbmmepb',
    'paid' => true,
    'state' => 'paid',
    'amount' => \Money\Money::MYR(200),
    'paid_amount' => \Money\Money::MYR(0),
    'due_at' => \Carbon\Carbon::parse('2020-12-31'),
    'email' => 'api@billplz.com',
    'mobile' => '+60112223333',
    'name' => 'MICHAEL API',
    'metadata' => [
        'id' => 9999,
        'description' => 'This is to test bill creation',
    ],
    'url' => 'https://billplz.dev/bills/W_79pJDk',
    'paid_at' => \Carbon\Carbon::parse('2015-03-09 16:23:59 +0800'),
];

获取账单

$response = $bill->show('8X0Iyzaw');

var_dump($response->toArray());
return [
    "id" => "8X0Iyzaw",
    "collection_id" => "inbmmepb",
    "paid" => false,
    "state" => "due",
    "amount" => \Money\Money::MYR(200),
    "paid_amount" => \Money\Money::MYR(0),
    "due_at" => \Carbon\Carbon::parse("2020-12-31"),
    "email" => "api@billplz.com",
    "mobile" => "+60112223333",
    "name" => "MICHAEL API V3",
    "url" => "https://www.billplz.com/bills/8X0Iyzaw",
    "reference_1_label" => "First Name",
    "reference_1" => "Jordan",
    "reference_2_label" => "Last Name",
    "reference_2" => "Michael",
    "redirect_url" => "http://example.com/redirect/",
    "callback_url" => "http://example.com/webhook/",
    "description" => "Maecenas eu placerat ante."
]

删除账单

$response = $bill->destroy('8X0Iyzaw');

var_dump($response->toArray());
[]

创建 Transaction 请求

现在您可以创建一个 Transaction 实例

$transaction = $billplz->transaction();

您还可以通过执行 $billplz->transaction('v3'); 手动设置 API 版本。您还可以使用 $billplz->resource('Bill.Transaction'); 来获取相同的结果。

获取交易索引

您可以通过调用以下代码来获取交易索引

$response = $transaction->show('inbmmepb');

var_dump($response->toArray());
return [
    "bill_id" => "inbmmepb"
    "transactions" => [
        [
            "id": "60793D4707CD",
            "status": "completed",
            "completed_at": "2017-02-23T12:49:23.612+08:00",
            "payment_channel": "FPX"
        ],
        [
            "id" => "28F3D3194138",
            "status" => "failed",
            "completed_at" => ,
            "payment_channel" => "FPX"
        ]
    ],
    "page" => 1
]

您还可以提供可选参数（页面、状态）

$response = $transaction->show('8X0Iyzaw', [
    'page' => 1,
    'status' => 'completed'
]);

var_dump($response->toArray());
return [
    "bill_id" => "8X0Iyzaw"
    "transactions" => [
        [
            "id" => "60793D4707CD",
            "status" => "completed",
            "completed_at" => "2017-02-23T12:49:23.612+08:00",
            "payment_channel" => "FPX"
        ]
    ],
    "page" => 1
]

创建 Bank 请求

现在您可以创建一个 Bank 实例

$bank = $billplz->bank();

您还可以通过执行 $billplz->bank('v3'); 手动设置 API 版本。您还可以使用 $billplz->resource('Bank'); 来获取相同的结果。

检查银行账户注册状态

在任何时候，您都可以通过银行账户号码请求检查注册状态。

$response = $bank->checkAccount('1234567890');

var_dump($response->toArray());
return [
    "name" => "verified"
]

获取 FPX 银行列表

如果您想在 Billplz 中使用银行直接功能，您需要在创建账单请求时提供 FPX 银行列表。

您可以通过以下代码获取支持的银行列表

$list = $bank->supportedForFpx();

var_dump($list->toArray());
return [
    "banks" => [
        [
            "name" => "PBB0233",
            "active" => true,
        ],
        [
            "name" => "MBB0227",
            "active" => true,
        ],
        [
            "name" => "MBB0228",
            "active" => true,
        ],
    ],
];

注意：如果您尚未通过 Billplz 启用银行直接功能，您将遇到 401、无效访问错误。请联系 Billplz 获取信息。

处理响应

对 Billplz 发出的每个请求都会返回 \Laravie\Codex\Response，该响应可以回退到 \Psr\Http\Message\ResponseInterface，这允许开发者进一步检查响应。

获取响应

您可以使用以下方式获取原始响应

$response->getBody();

然而，我们同时也创建了一种方法来解析返回的JSON字符串为数组。

$response->toArray();

检查响应 HTTP 状态

您可以通过以下方式获取响应状态码：

if ($response->getStatusCode() !== 200) {
    throw new SomethingHasGoneReallyBadException();
}

检查响应头

您还可以通过以下代码检查响应头：

$response->getHeaders(); // get all headers as array.
$response->hasHeader('Content-Type'); // check if `Content-Type` header exist.
$response->getHeader('Content-Type'); // get `Content-Type` header.