Skip to content

s950329/laravel-spgateway

BranchesTags

Repository files navigation

Laravel Spgateway

Latest Stable Version Total Downloads Latest Unstable Version License

Laravel Spgateway是一個開源的 智付通 非官方套件

目錄

  1. 環境要求
  2. 安裝
  3. 配置
  4. 使用
    1. 多功能收款MPG
    2. 電子發票
    3. 退款/取消授權
    4. 平台費用扣款指示
  5. 版本紀錄
  6. License

要求

  1. PHP >= 7.2.5
  2. Laravel >= 7
  3. Composer

安裝

$ composer require leochien/laravel-spgateway

配置

Laravel 應用

  1. 在 config/app.php 註冊 ServiceProvider 和 Facade (Laravel 5.5 無須手動註冊)
'providers' => [
    // ...
    LeoChien\Spgateway\SpgatewayServiceProvider::class,
],
'aliases' => [
    // ...
    'MPG' => LeoChien\Spgateway\Facades\MPG::class,
    'Receipt' => LeoChien\Spgateway\Facades\Receipt::class,
    'Refund' => LeoChien\Spgateway\Facades\Refund::class,
    'Transfer' => LeoChien\Spgateway\Facades\Transfer::class,
],
  1. 創建設定檔：
php artisan vendor:publish --provider="LeoChien\Spgateway\SpgatewayServiceProvider"

  1. 修改 config/spgateway.php 中對應的參數。

  2. 在 .env 中加入下列設定

# 金流系統設定
SPGATEWAY_HASH_KEY=
SPGATEWAY_HASH_IV=

# 金流合作推廣商系統設定
SPGATEWAY_COMPANY_KEY=
SPGATEWAY_COMPANY_IV=
SPGATEWAY_PARTNER_ID=
SPGATEWAY_MERCHANT_ID_PREFIX=
SPGATEWAY_MERCHANT_ID=

# 發票系統設定
SPGATEWAY_RECEIPT_KEY=
SPGATEWAY_RECEIPT_IV=
SPGATEWAY_RECEIPT_MERCHANT_ID=

使用

多功能收款MPG

快速上手

建立訂單

// 產生智付通訂單資料
$order = MPG::generate(
    100,
    '[email protected]',
    '測試商品'
);

// $order的 getPostData() 及 getPostDataEncrypted() 會回傳包含即將傳送到智付通的表單資料，可在此時紀錄log

// 前台送出表單到智付通
return $order->send();

解析智付通回傳訂單資料

$tradeInfo = MPG::parse(request()->TradeInfo);

查詢訂單

$order = MPG::search(
    '20180110151950mTHuUY'
    100
);

可用方法

generate ($amount, $email, $itemDesc [, $params ])

產生智付通建立訂單必要欄位

參數
  1. amount (Integer): 訂單金額
  2. email (String): 訂購人Email
  3. itemDesc (String): 商品描述
  4. [ params (Array) ]: 其他可選參數，詳見下方參數表
回傳
  1. (Class): MPG Class實體，其中getPostData() 及 getPostDataEncrypted()會回傳即將送到智付通的表單資料
使用範例
$order = MPG::generate(
    100,
    '[email protected]',
    '測試商品'
);
參數表
欄位 型態 可選值 預設 備註
MerchantOrderNo Varchar(20) 商店自訂編號，若無填寫則由套件產生
LangType String zh-tw / en zh-tw
TradeLimit Number 60 ~ 900 180
ExpireDate String (Ymd) 範例：20171231
ReturnURL Url
NotifyURL Url
CustomerURL Url
ClientBackURL Url
EmailModify Number 0 / 1 1
LoginType Number 0 / 1 0
OrderComment String
TokenTerm String 信用卡快速結帳
CREDIT Number 0 / 1 信用卡一次付清
CreditRed Number 0 / 1 信用卡紅利
InstFlag Number 0 / 1 信用卡分期付款
UNIONPAY Number 0 / 1 銀聯卡
WEBATM Number 0 / 1 WebATM
VACC Number 0 / 1 ATM轉帳
CVS Number 0 / 1 超商代碼繳費
BARCODE Number 0 / 1 條碼繳費，訂單金額需介於20～20000
CREDITAGREEMENT Number 0 / 1 約定信用卡授權
TokenLife String 約定信用卡付款之有效日期，範例：1912（2019-12）
備註
  • 支付方式若無選擇，默認開啟智付通後台設定方式
  • 若無傳送訂單編號預設會建立年月日時分秒+6位隨機字串的訂單編號，e.g. 20180110151950mTHuUY

send ()

前台送出智付通訂單建立表單

使用範例
$order->send();

parse ($tradeInfo)

解析智付通交易結果回傳參數，也適用於取號完成

參數
  1. tradeInfo (String): 智付通回傳，經AES加密之交易資料
回傳

詳見智付通文件第六節：交易支付系統回傳參數說明 / 第七節：取號完成系統回傳參數說明

{
    "Status": "..."
    "Message": "..."
    "Result": {...}
}
使用範例
$tradeInfo = MPG::parse(request()->TradeInfo);

search ($orderNo, $amount)

產生智付通查詢訂單必要欄位

參數
  1. orderNo (String): 訂單編號
  2. amount (Integer): 訂單金額
回傳

詳見智付通文件第四章：交易查詢系統回應訊息

{
    "Status": "..."
    "Message": "..."
    "Result": {...}
}
使用範例
// 查詢智付通訂單
$order = MPG::search(
    '20180110151950mTHuUY'
    100
);

電子發票

快速上手

開立發票

// 產生智付通開立發票資料
$receipt = Receipt::generate([
    'BuyerName'       => 'Leo',
    'TotalAmt'        => 10,
    'ItemName'        => [1],
    'ItemCount'       => [1],
    'ItemUnit'        => ['式'],
    'ItemPrice'       => [10],
]);

// $receipt的 getPostData() 及 getPostDataEncrypted 會回傳即將傳送到智付通的表單資料，可在此時紀錄log

// 送出開立發票申請，取得發票開立回傳結果
$res = $receipt->send();

觸發開立發票

// 產生智付通出發開立發票資料
$receipt = Receipt::generateTrigger('17122817285242624', '20171121WJNBX5NNBP', 100);

// $receipt的 getTriggerPostData() 及 getTriggerPostDataEncrypted() 會回傳即將傳送到智付通的表單資料，可在此時紀錄log

// 送出觸發開立發票申請，取得發票觸發開立回傳結果
$res = $receipt->send();

作廢發票

// 產生智付通作廢發票資料
$receipt = Receipt::generateInvalid('YF83646422', '作廢原因');

// $receipt的 getInvalidPostData() 及 getInvalidPostDataEncrypted() 會回傳即將傳送到智付通的表單資料，可在此時紀錄log

// 送出作廢發票申請，取得作廢發票回傳結果
$res = $receipt->sendInvalid();

查詢發票

// 查詢發票資料
$receipt = Receipt::search('20171121WJNBX5NNBP', 100);

可用方法

generate ($params)

產生智付通開立電子發票必要欄位

參數
  1. params (Array): 詳見下方可選參數
回傳
  1. (Class): Class實體，其中getPostData() 及 getPostDataEncrypted()包含即將送到智付通的表單資料
使用範例
$receipt = Receipt::generate([
    'BuyerName'       => 'Leo',
    'TotalAmt'        => 10,
    'ItemName'        => [1],
    'ItemCount'       => [1],
    'ItemUnit'        => ['式'],
    'ItemPrice'       => [10],
]);
可選參數
欄位 必填 型態 可選值 預設 備註
TransNum String 智付寶平台交易序號
MerchantOrderNo String 商店自訂編號，若無填寫則由套件產生
Status Number 0 / 1 / 3 1 開立發票方式
CreateStatusTime String (Y-m-d) 範例：2017-12-31
Category String B2B / B2C B2C
BuyerName ✔ String
BuyerUBN String
BuyerAddress String
BuyerEmail Email
CarrierType String 0 / 1 1
CarrierNum String 0 / 1 0
LoveCode Number
PrintFlag String Y / N Y
TaxType String 1 / 2 / 3 / 9 1
TaxRate Number 5
CustomsClearance Number 1 / 2
Amt Number 若無填寫則由套件計算
AmtSales Number
AmtZero Number
AmtFree Number
TaxAmt Number 若無填寫則由套件計算
TotalAmt ✔ Number
ItemName ✔ Array
ItemCount ✔ Array
ItemUnit ✔ Array
ItemPrice ✔ Array
ItemTaxType Array
ItemAmt Array 若無填寫則由套件計算
Comment String
備註
  • 本套件僅提供快速串接方式，詳細稅額計算方式請務必與公司財會人員進行確認

send()

傳送開立發票請求到智付通

回傳

詳見智付通文件第四節之二：開立發票系統回應訊息

{
    "Status": "..."
    "Message": "..."
    "Result": {...}
}
使用範例
$res = $receipt->send();

generateTrigger ($invoiceTransNo, $orderNo, $amount)

產生智付通觸發開立電子發票必要資訊

參數
  1. invoiceTransNo (String): 智付寶開立序號
  2. orderNo (String): 商店自訂編號
  3. amount (Integer): 發票金額
回傳
  1. (Class): Class實體，其中getTriggerPostData() 及 getTriggerPostDataEncrypted()會回傳即將送到智付通的表單資料
使用範例
$receipt = Receipt::generateTrigger('17122817285242624', '20171121WJNBX5NNBP', 100);

sendTrigger()

送出觸發開立電子發票請求到智付通

回傳

詳見智付通文件第四節之四：觸發開立發票系統回應訊息

{
    "Status": "..."
    "Message": "..."
    "Result": {...}
}
使用範例
$res = $receipt->sendTrigger();

generateInvalid ($receiptNumber, $invalidReason)

產生智付通觸發開立電子發票必要資訊

參數
  1. receiptNumber (String): 發票號碼
  2. receiptNumber (String): 作廢原因
回傳
  1. (Class): Class實體，其中getInvalidPostData() 及 getInvalidPostDataEncrypted()會回傳即將送到智付通的表單資料
使用範例
$receipt = Receipt::generateInvalid('17122817285242624', '作廢原因');

sendInvalid()

送出觸發開立電子發票請求到智付通

回傳

詳見智付通文件第五節之二：作廢發票系統回應訊息

{
    "Status": "..."
    "Message": "..."
    "Result": {...}
}
使用範例
$res = $receipt->sendInvalid();

search($orderNo, $amount)

查詢發票

參數
  1. orderNo (String): 商店自訂編號
  2. amount (Integer): 發票金額
回傳

詳見智付通文件第七節之二：查詢發票系統回應訊息

{
    "Status": "..."
    "Message": "..."
    "Result": {...}
}
使用範例
$res = $receipt->search('20171121WJNBX5NNBP', 100);

退款/取消授權

因智付通信用卡退費有尚未請款需串接取消授權API，已請款需串接退款API之規則，本功能旨在整合此一過程，降低開發人員負擔 另外也提供非即時交易退款功能

快速上手

// 產生智付通退費 / 取消授權必要資訊
$refund = Refund::generate('20171121WJNBX5NNBP', 100);

// $refund的 postType為cacnel時，訂單準備取消授權；為refund時，訂單準備退款
// $refund的 getPostData() 及 getPostDataEncrypted() 會回傳即將傳送到智付通的表單資料，可在此時紀錄log

// 送出退款/取消授權申請，取得回傳結果
$res = $refund->send();

可用方法

generate ($orderNo, $amount[, $notifyUrl = null, $delayed = false, $params = []])

產生智付通退費 / 取消授權必要欄位

參數
  1. orderNo (String): 商店自訂編號
  2. amount (String): 訂單金額，若不想全額退款請於可選參數中傳送Amt欄位
  3. [ notifyUrl (String) ]: 接受取消授權結果位址，於取消授權或非即時交易時才需填寫
  4. [ delayed (Boolean) ]: 是否為非即時交易
  5. [ params (Array) ]: 詳見下方參數表
回傳
  1. (Class): Class實體，其中getPostData() 及 getPostDataEncrypted()包含即將送到智付通的表單資料；getPostType()為cacnel時，訂單準備取消授權，為refund時，訂單準備退款
使用範例
$refund = Refund::generate('20171121WJNBX5NNBP', 100);
可選參數
  1. 即時交易
欄位 必填 型態 備註
RefundAmt Number 請退款金額，若發動退費後不退全額則需傳送此參數
  1. 非即時交易
欄位 必填 型態 備註
AccNo ✔ String 退款金額轉入之帳號
BankNo ✔ String 金融機構總行代號
SubBankCode ✔ String 金融機構分行代號
AccName ✔ String 帳戶使用名稱
RefundAmt ✔ Number 退款金額，必須小於等於訂單金額
Id + String 買方身分證字號，Id及UBN需擇一填寫
UBN + String 買方統一編號，Id及UBN需擇一填寫

send()

傳送退費 / 取消授權請求到智付通

回傳

取消授權：詳見智付通文件第五節：取消授權完成後系統回應訊息

退款：詳見智付通文件第五節：系統回應訊息

{
    "Status": "..."
    "Message": "..."
    "Result": {...}
}
使用範例
$res = $refund->send();

已約定信用卡付款

快速上手

// 產生付款必要資訊
$charge = Charge::generate(
    100,
    '[email protected]',
    'itemDesc',
    'xxxxxxxxxxxxxxxxxx',
    'xxx',
    [
        'MerchantOrderNo' => '20171121WJNBX5NNBP'
    ]
);

// $transfer的 getPostData() 及 getPostDataEncrypted() 會回傳即將傳送到智付通的表單資料，可在此時紀錄log

// 送出扣款
$res = $charge->send();

可用方法

generate ($amount, $email, $itemDesc, $tokenValue, $tokenTerm, $params)

產生已約定信用卡付款必要欄位

參數
  1. $amount (String): 金額
  2. $email (String): 購買人 Email
  3. $itemDesc (Integer): 商品描述
  4. $tokenValue (Integer): 約定信用卡授權碼
  5. $tokenTerm (): 約定信用卡付款之付款人綁定資料
  6. $params (): 可選選項
可選參數
欄位 必填 型態 備註
MerchantOrderNo String 訂單編號
TokenSwitch String 當此參數為”on”時，才會啟用約定信用卡付款授權功能
回傳
  1. (Class): Class實體，其中 getPostData() 及 getPostDataEncrypted() 包含即將送到智付通的表單資料
使用範例
$charge = Charge::generate(
    100,
    '[email protected]',
    'itemDesc',
    'xxxxxxxxxxxxxxxxxx',
    'xxx',
    [
        'MerchantOrderNo' => '20171121WJNBX5NNBP'
    ]
);

send()

傳送已約定信用卡付款請求到智付通

回傳

本文件未公開，請向合作之智付通業務人員索取

{
    "Status": "..."
    "Message": "..."
    "Result": {...}
}
使用範例
$res = $transfer->send();

平台費用扣款指示

快速上手

// 產生平台費用扣款指示必要資訊
$transfer = Transfer::generate('20171121WJNBX5NNBP', 100, 0, 0);

// $transfer的 getPostData() 及 getPostDataEncrypted() 會回傳即將傳送到智付通的表單資料，可在此時紀錄log

// 送出扣款指示申請，取得扣款指示回傳結果
$res = $transfer->send();

可用方法

generate ($merchantID, $amount, $feeType, $balanceType)

產生智付通扣款指示必要欄位

參數
  1. orderNo (String): 商店自訂編號
  2. amount (String): 金額
  3. feeType (Integer): 費用類別
  4. balanceType (Integer): 交易正負值
回傳
  1. (Class): Class實體，其中getPostData() 及 getPostDataEncrypted()包含即將送到智付通的表單資料
使用範例
$transfer = Transfer::generate('20171121WJNBX5NNBP', 100);

send()

傳送扣款指示請求到智付通

回傳

本文件未公開，請向合作之智付通業務人員索取

{
    "Status": "..."
    "Message": "..."
    "Result": {...}
}
使用範例
$res = $transfer->send();

版本紀錄

1.1.0

  1. 非信用卡退款
  2. MPG交易串接增加支付寶欄位（測試功能）

1.0.0

  1. MPG交易串接 / 查詢
  2. 電子發票
  3. 退款 / 取消授權
  4. 平台扣款指示

License

Laravel Spgateway is open-sourced software licensed under the MIT license

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

34 stars

Watchers

3 watching

Forks

20 forks
Report repository

Releases 23

支援 Laravel 8.x Latest
Sep 10, 2020
+ 22 releases

Packages

No packages published

Contributors 5

Languages