voicetube/taiwan-payment-gateway

A payment gateway library for Taiwan.

v1.5.8@RC 2020-11-17 06:36 UTC

Requires

• php: >=7.2.5
• guzzlehttp/guzzle: ^7

Requires (Dev)

• phpmd/phpmd: ^2.8
• phpunit/phpunit: 9.0
• squizlabs/php_codesniffer: ^3.5

MIT

• Merik Chen

• payment
• gateway
• Taiwan
• VoiceTube

README

A payment gateway library for Taiwan.

Created by VoiceTube

Features

• Create / Process order
• Unit-Testing with PHPUnit
• PSR-4 auto-loading compliant structure
• Support PHPStorm meta for auto-completion
• Easy to use to any framework or even a plain php file

Todo

• Payment status
• E-Invoice features
• Credit Card cancel / refund API

Available Gateway

• 智付通 Spgateway
• 歐付寶 allPay
• 綠界 ECPay

How to use

Accept payment method.

• WebATM
• BarCode
• TenPay (AllPay only)
• TopUp (AllPay only)
• Credit
• ATM
• CVS
• ALL (AllPay, EcPay only)

Load the library

require_once 'vendor/autoload.php';

use VoiceTube\TaiwanPaymentGateway;

Initial the gateway

/**
* Use factory to create gateway or directly new the gateway
*/

$gw = TaiwanPaymentGateway\TaiwanPaymentGateway::create('SpGateway', [
    'hashKey'       => 'c7fe1bfba42369ec1add502c9917e14d',
    'hashIV'        => '245a49c8fb5151f0',
    'merchantId'    => 'MS1234567',
    'version'       => '1.2',
    'actionUrl'     => 'https://ccore.spgateway.com/MPG/mpg_gateway',
    'returnUrl'     => 'https://localhost/payment/confirm',
    'notifyUrl'     => 'https://localhost/payment/notify',
    'clientBackUrl' => 'https://localhost/payment/return',
    'paymentInfoUrl'=> 'https://localhost/payment/information',
]);


$sp = new TaiwanPaymentGateway\SpGatewayPaymentGateway([
    'hashKey'       => 'c7fe1bfba42369ec1add502c9917e14d',
    'hashIV'        => '245a49c8fb5151f0',
    'merchantId'    => 'MS1234567',
    'version'       => '1.2',
    'actionUrl'     => 'https://ccore.spgateway.com/MPG/mpg_gateway',
    'returnUrl'     => 'https://localhost/payment/confirm',
    'notifyUrl'     => 'https://localhost/payment/notify',
    'clientBackUrl' => 'https://localhost/payment/return',
    'paymentInfoUrl'=> 'https://localhost/payment/information',
]);

$ec = new TaiwanPaymentGateway\EcPayPaymentGateway([
    'hashKey'       => '5294y06JbISpM5x9',
    'hashIV'        => 'v77hoKGq4kWxNNIS',
    'merchantId'    => '2000132',
    'version'       => 'V4',
    'actionUrl'     => 'https://payment-stage.ecpay.com.tw/Cashier/AioCheckOut/',
    'returnUrl'     => 'https://localhost/payment/confirm',
    'clientBackUrl' => 'https://localhost/payment/return',
    'paymentInfoUrl'=> 'https://localhost/payment/information',
]);

$ap = new TaiwanPaymentGateway\AllPayPaymentGateway([
    'hashKey'       => '5294y06JbISpM5x9',
    'hashIV'        => 'v77hoKGq4kWxNNIS',
    'merchantId'    => '2000132',
    'version'       => 'V2',
    'actionUrl'     => 'https://payment-stage.allpay.com.tw/Cashier/AioCheckOut/',
    'returnUrl'     => 'https://localhost/payment/confirm',
    'clientBackUrl' => 'https://localhost/payment/return',
    'paymentInfoUrl'=> 'https://localhost/payment/information',
]);

New order

!! All order settings must called after create new order, or the $gw->newOrder() function will erase all previously order data.

// create new order
// $respond_type:
//  SpGateway: `POST` or `JSON` (default to 'JSON')
//  AllPay, EcPay: `POST` only
$gw->newOrder(
    required:$merchant_order_no, 
    required:$amount, 
    required:$item_describe, 
    required:$order_comment, 
    optional:$respond_type, 
    optional:$timestamp
);

// Available payment method
$gw->useBarCode();
$gw->useWebATM();
$gw->useCredit();
$gw->useTenPay(); // AllPay only
$gw->useTopUp(); // AllPay only
$gw->useATM();
$gw->useCVS();
$gw->useALL(); // AllPay, EcPay only

// spgateway only settings
$gw->setEmail('[e-mail]'); // setting user email
$gw->triggerEmailModify(optional:boolean); // allow user update email address later.
$gw->onlyLoginMemberCanPay(optional:boolean); // force user must to be login later.

// Order settings
$gw->setUnionPay();
$gw->needExtraPaidInfo();
$gw->setCreditInstallment(required:$months, optional:$total_amount);
$gw->setOrderExpire(required:$expire_Date);

// It can be using like this

$rId = sprintf("VT%s", time());
$gw->newOrder($rId, 100, rId, $rId)
   ->useCredit()
   ->setUnionPay()
   ->needExtraPaidInfo();

// generate post form
$gw->genForm(optional:$auto_submit = true);

Process order result/information

Initial the gateway

/**
* Use factory to create response or directly new the response
*/

$gwr = TaiwanPaymentGateway\TaiwanPaymentResponse::create('SpGateway', [
    'hashKey'       => 'c7fe1bfba42369ec1add502c9917e14d',
    'hashIV'        => '245a49c8fb5151f0',
]);

$spr = new TaiwanPaymentGateway\SpGatewayPaymentResponse([
    'hashKey'       => 'c7fe1bfba42369ec1add502c9917e14d',
    'hashIV'        => '245a49c8fb5151f0',
]);

$ecr = new TaiwanPaymentGateway\EcPayPaymentResponse([
    'hashKey'       => '5294y06JbISpM5x9',
    'hashIV'        => 'v77hoKGq4kWxNNIS',
]);

$apr = new TaiwanPaymentGateway\AllPayPaymentResponse([
    'hashKey'       => '5294y06JbISpM5x9',
    'hashIV'        => 'v77hoKGq4kWxNNIS',
]);

Check the payment response

// processOrder will catch $_POST fields and clean it
// SpGateway: `POST` or `JSON`
// AllPay, EcPay: `POST` only
$result = $spr->processOrder(optional:$type='POST or JSON');

// dump the result
array(22) {
  ["Status"]=>
  string(7) "SUCCESS"
  ["Message"]=>
  string(12) "授權成功"
  ["MerchantID"]=>
  string(9) "MS1234567"
  ["Amt"]=>
  int(1200)
  ["TradeNo"]=>
  string(17) "17032311330952317"
  ["MerchantOrderNo"]=>
  string(15) "1703230034715"
  ["PaymentType"]=>
  string(6) "CREDIT"
  ["RespondType"]=>
  string(6) "String"
  ["CheckCode"]=>
  string(64) "4B3DDA5FE88966928FEB903D6037B06A1A929087046E5E8D7A8CB2778A30D67C"
  ["PayTime"]=>
  string(19) "2017-03-23 11:33:09"
  ["IP"]=>
  string(12) "XXX.XXX.XXX.XXX"
  ["EscrowBank"]=>
  string(3) "KGI"
  ["TokenUseStatus"]=>
  int(0)
  ["RespondCode"]=>
  string(2) "00"
  ["Auth"]=>
  string(6) "930637"
  ["Card6No"]=>
  string(6) "400022"
  ["Card4No"]=>
  string(4) "1111"
  ["Inst"]=>
  int(0)
  ["InstFirst"]=>
  int(1200)
  ["InstEach"]=>
  int(0)
  ["ECI"]=>
  string(0) ""
  ["matched"]=>
  bool(true)
}

// after processing, check the `matched` field.

// for allpay and ecpay, you will need to call `rspOk` or `rspError`.
$ecr->rspOk();
// or
$apr->rspError(optinal:'Custom error msg');

Ref.

• [PDF] SpGateway
• [PDF] AllPay
• [PDF] EcPay