jomweb/billplz

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

维护者

详情

github.com/jomweb/billplz

源代码

问题

资助包维护！
crynobone
Liberapay
paypal.me/crynobone

安装次数: 172,091

依赖: 3

建议者: 0

安全: 0

星标: 74

关注者: 12

分支: 29

公开问题: 2

v5.2.0 2024-03-31 14:09 UTC

Requires

Requires (Dev)

MIT 7e55fdd4eac2b76b2c2032f65fdf3de047662614

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

This package is auto-updated.

Last update: 2024-08-31 00:38:43 UTC

README

tests Latest Stable Version Total Downloads Latest Unstable Version License Coverage Status

安装

Composer

使用以下命令通过Composer安装

composer require php-http/guzzle7-adapter jomweb/billplz:^4.1

HTTP适配器

除了使用php-http/guzzle7-adapter，您可能想要使用任何实现了php-http/client-implementation的适配器。请参阅PHP-HTTP的客户端和适配器。

PHAR

如果您的应用程序中不可用Composer，您可以选择使用Billplz PHAR，可以从最新的GitHub发行版下载。此构建使用guzzlehttp/guzzle在所有Billplz API请求中。

您应该收到billplz.phar文件，您可以将它包含到您的项目中。

<?php

require "billplz.phar";

$client = Billplz\Client::make('your-api-key', 'your-x-signature-key');

入门指南

创建客户端

您可以通过以下代码创建Billplz客户端开始（它使用php-http/guzzle6-adapter和php-http/discovery自动选择通过Composer安装的适配器）

<?php

use Billplz\Client;

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

您也可以通过以下方式发送X-Signature密钥

<?php

use Billplz\Client;

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

或者，您也可以直接手动配置Http\Client\Common\HttpMethodsClient

<?php

use Billplz\Client;

$http = Laravie\Codex\Discovery::client();

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

使用沙箱

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

$billplz->useSandbox();

API版本

默认情况下，jomweb/billplz会使用v4 API版本进行所有请求，但是当新的API版本可用时，您可以在未来自定义此设置。

$billplz->useVersion('v3');

用法

集合

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

$collection = $billplz->collection();

您也可以通过以下方式手动设置API版本：$billplz->collection('v3');。您还可以使用$billplz->uses('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' => \Duit\MYR::given(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" => \Duit\MYR::given(100),
        "variable_cut" => null,
    ],
];

集合列表

您可以通过调用以下代码获取集合索引

$response = $collection->all();

var_dump($response->toArray());
return [
    "collections": [{
        "id" => "inbmmepb",
        "title" => "My First API Collection",
        "logo" => [
            "thumb_url" => null,
            "avatar_url" => null,
        ],
        "split_header" => null,
        "split_payments" => [
            [
                "email" => "verified@account.com",
                "fixed_cut" => 100,
                "variable_cut" => 2,
                "stack_order" => 0,
            ],
            [
                "email" => "verified2@account.com",
                "fixed_cut" => 200,
                "variable_cut" => 3,
                "stack_order" => 1,
            ],
        ],
        "status" => "active",
    }],
    "page" => 1,
];

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

$response = $collection->all([
    'page' => 2,
    'status' => 'active',
]);

var_dump($response->toArray());
return [
    "collections": [{
        "id" => "inbmmepb",
        "title" => "My First API Collection",
        "logo" => [
            "thumb_url" => null,
            "avatar_url" => null,
        ],
        "split_header" => null,
        "split_payments" => [
            [
                "email" => "verified@account.com",
                "fixed_cut" => 100,
                "variable_cut" => 2,
                "stack_order" => 0,
            ],
            [
                "email" => "verified2@account.com",
                "fixed_cut" => 200,
                "variable_cut" => 3,
                "stack_order" => 1,
            ],
        ],
        "status" => "active",
    }],
    "page" => 2,
];

获取现有集合

您可以通过调用以下代码获取现有集合

$response = $collection->get('inbmmepb');

var_dump($response->toArray());
return [
    "id" => "inbmmepb",
    "title" => "My First API Collection",
    "logo" => [
        "thumb_url" => null,
        "avatar_url" => null,
    ],
    "split_header" => null,
    "split_payments" => [
        [
            "email" => "verified@account.com",
            "fixed_cut" => 100,
            "variable_cut" => 2,
            "stack_order" => 0,
        ],
        [
            "email" => "verified2@account.com",
            "fixed_cut" => 200,
            "variable_cut" => 3,
            "stack_order" => 1,
        ],
    ],
    "status" => "active",
];

停用集合

要使用 activate() 和 deactivate() 函数，您必须明确使用版本 v3。您可以通过以下代码来禁用收藏集

$response = $collection->deactivate('inbmmepb');

激活集合

您也可以通过以下代码来禁用收藏集

$response = $collection->deactivate('inbmmepb');

打开集合

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

$collection = $billplz->openCollection();

您还可以通过执行 $billplz->openCollection('v3'); 来手动设置API版本。您也可以使用 $billplz->uses('OpenCollection'); 来得到相同的结果。

创建开放集合

$response = $collection->create(
    'My First API Collection',
    'Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst.',
    \Duit\MYR::given(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" => \Duit\MYR::given(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",
];

开放集合列表

您可以通过以下代码来获取 Open Collection 索引

$response = $collection->all();

var_dump($response->toArray());
return [
    "open_collections": [{
        "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" => \Duit\MYR::given(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",
    }],
    "page" => 1,
];

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

$response = $collection->all([
    'page' => 2,
    'status' => 'active',
]);

var_dump($response->toArray());
return [
    "open_collections": [{
        "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" => \Duit\MYR::given(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",
    }],
    "page" => 2
];

获取现有开放集合

您可以通过以下代码来获取现有的开放收藏集

$response = $collection->get('0pp87t_6');

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" => \Duit\MYR::given(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 = $billplz->bill();

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

创建账单

您可以通过以下代码来添加一个新的账单

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

var_dump($response->toArray());
return [
    "id" => "8X0Iyzaw",
    "collection_id" => "inbmmepb",
    "paid" => false,
    "state" => "overdue",
    "amount" => \Duit\MYR::given(200),
    "paid_amount" => \Duit\MYR::given(0),
    "due_at" => new \DateTime('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."
];

redirect_url 可以通过第8个参数传递，即 (array) $optional

设置重定向URL的替代方法
$response = $bill->create(
    'inbmmepb',
    'api@billplz.com',
    null,
    'Michael API V3',
    \Duit\MYR::given(200),
    'http://example.com/webook/',
    'Maecenas eu placerat ante.',
    ['redirect_url' => 'http://example.com/redirect/']
);

var_dump($response->toArray());
return [
    "id" => "8X0Iyzaw",
    "collection_id" => "inbmmepb",
    "paid" => false,
    "state" => "overdue",
    "amount" => \Duit\MYR::given(200),
    "paid_amount" => \Duit\MYR::given(0),
    "due_at" => new \DateTime('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" => "http://example.com/redirect/",
    "callback_url" => "http://example.com/webhook/",
    "description" => "Maecenas eu placerat ante."
];

获取现有账单

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

var_dump($response->toArray());
return [
    "id" => "8X0Iyzaw",
    "collection_id" => "inbmmepb",
    "paid" => false,
    "state" => "due",
    "amount" => \Duit\MYR::given(200),
    "paid_amount" => \Duit\MYR::given(0),
    "due_at" => new \DateTime("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());
[]

支付完成

重定向

您可以为用户支付完成后重定向的页面设置重定向页面。Billplz 将将用户重定向到您指定的重定向页面，并附带一些URL参数。为了捕获所有URL参数，请执行以下操作。

$data = $bill->redirect($_GET);
return [
    'id' => 'W_79pJDk',
    'paid' => true,
    'paid_at' => new \DateTime('2015-03-09 16:23:59 +0800'),
];

如果您在Billplz API设置中启用了“额外支付完成信息”，您将收到以下输出

return [
    'id' => 'W_79pJDk',
    'paid' => true,
    'paid_at' => new \DateTime('2015-03-09 16:23:59 +0800'),
    'transaction_id' => 'AC4GC031F42H',
    'transaction_status' => 'completed',
];

回调

您可以通过设置webhook来接收来自Billplz的POST请求。为了接受响应，您只需编写以下代码。

$data = $bill->webhook($_POST);
return [
    'id' => 'W_79pJDk',
    'collection_id' => 'inbmmepb',
    'paid' => true,
    'state' => 'paid',
    'amount' => \Duit\MYR::given(200),
    'paid_amount' => \Duit\MYR::given(0),
    'due_at' => new \DateTime('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' => new \DateTime('2015-03-09 16:23:59 +0800'),
];

如果您在Billplz API设置中启用了“额外支付完成信息”，您将收到以下输出

return [
    'id' => 'W_79pJDk',
    'collection_id' => 'inbmmepb',
    'paid' => true,
    'state' => 'paid',
    'amount' => \Duit\MYR::given(200),
    'paid_amount' => \Duit\MYR::given(0),
    'due_at' => new \DateTime('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' => new \DateTime('2015-03-09 16:23:59 +0800'),
    'transaction_id' => 'AC4GC031F42H',
    'transaction_status' => 'completed',
];

交易

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

$transaction = $billplz->transaction();

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

交易列表

您可以通过以下代码来获取Transaction索引

$response = $transaction->get('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->get('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 = $billplz->bank();

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

创建银行账户

通过创建通过此API的银行记录来请求银行直接验证服务。

$response = $bank->createAccount('Insan Jaya', '91234567890', '999988887777', 'MBBEMYKL', true);

var_dump($response->toArray());
return [
    "name" => "Insan Jaya",
    "id_no" => "91234567890",
    "acc_no" => "999988887777",
    "code" => "MBBEMYKL",
    "organization" => true,
    "authorization_date" => "2017-07-03",
    "status" => "pending",
    "processed_at" => null,
    "rejected_desc" => null
]

获取银行账户

通过传递单个账户号码参数查询Billplz银行直接验证服务。此API将只返回最新、单个匹配的银行账户。

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

var_dump($response->toArray());
return [
    "name" => "sara",
    "id_no" => "820909101001",
    "acc_no" => "1234567890",
    "code" => "MBBEMYKL",
    "organization" => false,
    "authorization_date" => "2015-12-03",
    "status" => "pending",
    "processed_at" => null,
    "rejected_desc" => null
]

通过银行账户进行注册检查

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

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

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

获取FPX银行列表

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

您可以通过以下代码来获取支持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获取信息。

支付订单集合

创建支付订单收藏集实例

$paymentOrderCollection = $billplz->paymentOrderCollection();

创建支付订单收藏集

$response = $paymentOrderCollection->create(
    'My First API Payment Order Collection'
);

var_dump($response->toArray());

获取支付订单收藏集

$response = $paymentOrderCollection->get(
    '8f4e331f-ac71-435e-a870-72fe520b4563'
);

var_dump($response->toArray());

支付订单

创建支付订单实例

$paymentOrder = $billplz->paymentOrder();

创建支付订单

$response = $paymentOrder->create(
    '8f4e331f-ac71-435e-a870-72fe520b4563',
    'MBBEMYKL',
    '543478924652',
    '820808062202',
    'Michael Yap',
    'Maecenas eu placerat ante.',
    2000
);

var_dump($response->toArray());

注意：如果您尝试使用超过您的支付订单限额的总额进行支付，将遇到422，支付不足错误。

获取支付订单

$response = $paymentOrder->get(
    'cc92738f-dfda-4969-91dc-22a44afc7e26'
);

var_dump($response->toArray());

获取支付订单限制

$response = $paymentOrder->limit();

var_dump($response->toArray());

处理响应

对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.