Stars: 242
Forks: 83
Pull Requests: 0
Issues: 5
Watchers: 22
Last Updated: 2021-01-01 12:55:56
A Ping++ driver for the Omnipay PHP payment processing library. 一个聚合了支付宝(APP、Wap、PC、即时到账、扫码、企业付款),微信(APP、公众号、红包), 银联网关、银联企业网银、Apple Pay、QQ 钱包、易宝支付、百度钱包、京东支付、京东白条、招行一网通、分期支付等国内主流支付渠道的聚合支付网关(Ping++, also known as Pingpp/Pingxx/Pingplusplus)
License: MIT License
Languages: Shell, PHP
Ping++ driver for the Omnipay PHP payment processing library
Ping++ is a Chinese leading payment integration service provider, which support various mainstream payment gateways in China, eg. Alipay, Wechat Pay, UnionPay, Apple Pay, QQ Wallet, YeePay, Baidu Wallet, JDPay, etc.
Omnipay is a framework agnostic, multi-gateway payment processing library for PHP. It has a clear and consistent API, and is fully unit tested. This package implements Ping++ support for Omnipay.
Omnipay is installed via Composer. To install, simply add it
to your composer.json
file:
{
"require": {
"phoenixg/omnipay-pingpp": "^1.0"
}
}
And run composer to update your dependencies:
$ curl -s http://getcomposer.org/installer | php
$ php composer.phar update
The following gateways are provided by this package:
For general usage instructions, please see the main Omnipay repository.
require './vendor/autoload.php';
use Omnipay\Omnipay;
use Omnipay\Pingpp\Common\Helpers;
use Omnipay\Pingpp\Common\Channels;
/**
* Get key and App ID in Ping++ Dashboard: https://dashboard.pingxx.com/
*/
$skLiveKey = 'sk_live_************************';
$appId = 'app_****************';
/**
* The payment channel you have configured in Ping++
*/
$channel = Channels::ALIPAY_WAP;
try {
/**
* @var $gateway \Omnipay\Pingpp\Gateway
*/
$gateway = Omnipay::create('Pingpp');
$gateway->initialize(array(
'apiKey' => $skLiveKey, // if test key is passed, all transactions will happen in test mode
'privateKey' => file_get_contents(PINGPP_ASSET_DIR.'/sample_rsa_private_key.pem') // optional, see: https://help.pingxx.com/article/123161/
));
} catch (\Exception $e) {
echo $e->getMessage();
}
METHOD | INTRODUCTION |
---|---|
$gateway->purchase() |
创建 Charge |
$gateway->fetchTransaction() |
查询单笔 Charge |
$gateway->fetchTransactionList() |
查询 Charge 列表 |
$gateway->reverse() |
撤销 Charge(仅支持isv线下渠道,如已支付会退款) |
$gateway->refund() |
创建退款 |
$gateway->fetchRefund() |
查询单笔退款 |
$gateway->fetchRefundList() |
查询退款列表 |
$gateway->batchRefund() |
创建批量退款 |
$gateway->fetchBatchRefund() |
查询单个批量退款批次号 |
$gateway->fetchBatchRefundList() |
查询批量退款列表 |
$gateway->redEnvelope() |
发送红包 |
$gateway->fetchRedEnvelope() |
查询单笔红包 |
$gateway->fetchRedEnvelopeList() |
查询红包列表 |
$gateway->transfer() |
创建转账 |
$gateway->cancelTransfer() |
取消转账 |
$gateway->fetchTransfer() |
查询单笔转账 |
$gateway->fetchTransferList() |
查询转账列表 |
$gateway->batchTransfer() |
创建批量转账 |
$gateway->fetchBatchTransfer() |
查询单个批量转账批次号 |
$gateway->cancelBatchTransfer() |
取消批量转账 |
$gateway->fetchEvent() |
查询 Event 事件(已废弃) |
channelExtraFields
参数参考 src/Common/ChargeChannelExtras.php
的说明
/**
* @var \Omnipay\Pingpp\Message\PurchaseRequest $transaction
*/
$transaction = $gateway->purchase(array(
'appId' => $appId,
'transactionId' => Helpers::generateTransactionId(),
'channel' => $channel,
'channelExtraFields' => array( // optional
'app_pay' => true
),
'subject' => 'Demo subject',
'body' => 'Demo body',
'description' => 'Demo description', // optional
'amount' => 0.01,
'currency' => 'cny',
'clientIp' => '127.0.0.1',
'timeExpire' => time() + 3600, // optional
'metadata' => array('foo' => 'bar'), // optional
'returnUrl' => 'http://yourdomain.com/path/to/awesome/return.php', // optional
'cancelUrl' => 'http://yourdomain.com/path/to/awesome/cancel.php', // optional
'notifyUrl' => 'http://yourdomain.com/path/to/awesome/notify.php', // optional
));
/**
* 以下 $response 的方法支持同上
* @var \Omnipay\Pingpp\Message\Response $response
*/
$response = $transaction->send();
if ($response->isSuccessful()) {
$reference_id = $response->getTransactionReference();
echo "Transaction reference = " . $reference_id .PHP_EOL;
echo json_encode($response->getData());die;
} else {
echo $response->getMessage();
}
/**
* @var \Omnipay\Pingpp\Message\FetchTransactionRequest $transaction
*/
$transaction = $gateway->fetchTransaction();
$transaction->setTransactionReference('ch_DaHuXHjHeX98GO84COzbfTiP');
$response = $transaction->send();
/**
* @var \Omnipay\Pingpp\Message\ReverseTransactionRequest $transaction
*/
$transaction = $gateway->reverse();
$transaction->setTransactionReference('ch_DaHuXHjHeX98GO84COzbfTiP');
$response = $transaction->send();
/**
* @var \Omnipay\Pingpp\Message\FetchTransactionListRequest $transactionList
*/
$transactionList = $gateway->fetchTransactionList(array(
'appId' => $appId,
'channel' => Channels::ALIPAY,
'paid' => 0,
'refunded' => 0,
'createdFrom' => 1481116461,
'createdTo' => 1477723630,
'limit' => 5,
));
$response = $transactionList->send();
/**
* @var \Omnipay\Pingpp\Message\RefundRequest $refund
*/
$refund = $gateway->refund(array(
'amount' => '10.00',
'transactionReference' => 'ch_DaHuXHjHeX98GO84COzbfTiP',
'description' => 'Demo refund description',
'metadata' => array('foo' => 'bar'), // optional
));
$response = $refund->send();
/**
* @var \Omnipay\Pingpp\Message\FetchRefundRequest $refund
*/
$refund = $gateway->fetchRefund(array(
'transactionReference' => 'ch_qDun9KKC0uz9G0KSGKaHKybP',
'refundReference' => 're_Ouz5GSfv1Gm1S4WzTCaXXPSKs',
));
$response = $refund->send();
/**
* @var \Omnipay\Pingpp\Message\FetchRefundListRequest $refundList
*/
$refundList = $gateway->fetchRefundList(array(
'transactionReference' => 'ch_qDun9KKC0uz9G0KSGKaHKybP',
'limit' => 5,
));
$response = $refundList->send();
/**
* @var \Omnipay\Pingpp\Message\BatchRefundRequest $batchRefund
*/
$batchRefund = $gateway->batchRefund(array(
'app' => $appId,
'batchRefundReference' => Helpers::generateBatchRefundReference(),
'chargeIdList' => array(
'ch_L8qn10mLmr1GS8e5OODmHaL4',
'ch_fdOmHaLmLmr1GOD4qn1dS8e5',
),
'description' => 'Demo batch refund description.', // optional
'metadata' => array('foo' => 'bar'), // optional
));
$response = $batchRefund->send();
/**
* @var \Omnipay\Pingpp\Message\FetchBatchRefundRequest $batchRefund
*/
$batchRefund = $gateway->fetchBatchRefund();
$batchRefund->setBatchRefundReference('batch_refund_20160801001');
$response = $batchRefund->send();
/**
* @var \Omnipay\Pingpp\Message\FetchBatchRefundListRequest $batchRefundList
*/
$batchRefundList = $gateway->fetchBatchRefundList(array(
'appId' => $appId,
'limit' => 5,
));
$response = $batchRefundList->send();
/**
* @var \Omnipay\Pingpp\Message\RedEnvelopeRequest $redEnvelope
*/
$redEnvelope = $gateway->redEnvelope(array(
'appId' => $appId,
'transactionId' => Helpers::generateRedEnvelopeTransactionId(),
'channel' => Channels::WX, // only support "wx", "wx_pub" channel
'subject' => 'Demo subject',
'body' => 'Demo body',
'description' => 'Demo description', // optional
'amount' => 0.01,
'currency' => 'cny',
'sender' => 'Sender Name', // merchant name
'receiver' => 'Wechat Openid',
'metadata' => array('foo' => 'bar'), // optional
));
$response = $redEnvelope->send();
/**
* @var \Omnipay\Pingpp\Message\FetchRedEnvelopeRequest $redEnvelopeTransaction
*/
$redEnvelope = $gateway->fetchRedEnvelope();
$redEnvelope->setTransactionReference('red_KCabLO58W5G0rX90iT0az5a9');
$response = $redEnvelope->send();
/**
* @var \Omnipay\Pingpp\Message\FetchRedEnvelopeListRequest $redEnvelopeList
*/
$redEnvelopeList = $gateway->fetchRedEnvelopeList(array(
'appId' => $appId,
'limit' => 5,
));
$response = $redEnvelopeList->send();
channelExtraFields
参数参考 src/Common/TransferExtras.php
的说明
如果返回 请求来源存在风险,请联系Ping++。
报错, 是因为没有在 Ping++ 管理平台配置 IP 白名单, 默认是强制开启的。
/**
* @var \Omnipay\Pingpp\Message\TransferRequest $transfer
*/
$transfer = $gateway->transfer(array(
'appId' => $appId,
'channel' => Channels::WX_PUB, // only support "unionpay", "wx_pub" channel
'channelExtraFields' => array( // optional, different by channel
'user_name' => 'User Name',
'force_check' => true
),
'transactionId' => Helpers::generateTransferTransactionId(Channels::WX_PUB),
'description' => 'Demo description',
'amount' => 0.01,
'currency' => 'cny',
'type' => 'b2c',
'receiver' => 'Wechat Openid', // optional, different by channel
'metadata' => array('foo' => 'bar'), // optional
));
$response = $transfer->send();
/**
* @var \Omnipay\Pingpp\Message\CancelTransferRequest $cancel
*/
$cancel = $gateway->cancelTransfer();
$cancel->setTransactionReference('tr_0eTi1OGqr9iH0i9CePf1a9C0'); // only support "unionpay" channel
$response = $cancel->send();
/**
* @var \Omnipay\Pingpp\Message\FetchTransferRequest $transfer
*/
$transfer = $gateway->fetchTransfer();
$transfer->setTransactionReference('tr_HqbzHCvLOaL4La1ezHfDWTqH');
$response = $transfer->send();
/**
* @var \Omnipay\Pingpp\Message\FetchTransferListRequest $transferList
*/
$transferList = $gateway->fetchTransferList(array(
'appId' => $appId,
'limit' => 5,
));
$response = $transferList->send();
recipients
参数参考 src/Common/BatchTransferRecipients.php
的说明
/**
* @var \Omnipay\Pingpp\Message\BatchTransferRequest $batchTransfer
*/
$batchTransfer = $gateway->batchTransfer(array(
'app' => $appId,
'batchTransferReference' => Helpers::generateBatchTransferReference(),
'recipients' => array(
array(
'account' => 'alipay account for receiver',
'amount' => 0.01,
'name' => 'receiver name A',
'description' => '', // optional
),
array(
'account' => 'alipay account for receiver',
'amount' => 0.01,
'name' => 'receiver name B',
'description' => '', // optional
}
),
'channel' => Channels::ALIPAY, // only support "alipay", "unionpay" channel
'amount' => 0.02,
'description' => 'Demo batch transfer description.',
'currency' => 'cny',
'type' => 'b2c',
'metadata' => array('foo' => 'bar'), // optional
));
$response = $batchTransfer->send();
/**
* @var \Omnipay\Pingpp\Message\FetchBatchTransferRequest $batchTransfer
*/
$batchTransfer = $gateway->fetchBatchTransfer();
$batchTransfer->setBatchTransferReference('batch_no_20160801001');
$response = $batchTransfer->send();
/**
* @var \Omnipay\Pingpp\Message\CancelBatchTransferRequest $cancel
*/
$cancel = $gateway->cancelBatchTransfer();
$cancel->setTransactionReference('batch_no_20160801001');
$response = $cancel->send();
/**
* @var \Omnipay\Pingpp\Message\FetchEventRequest $event
*/
$event = $gateway->fetchEvent();
$event->setEventReference('evt_lqVSy5gbL0A68pS8YKvJzdWZ');
$response = $event->send();
To configure your webhooks URL, simply login Ping++ Dashboard, for more information, check out: docs
Code below shows how you can verify whether the webhooks you receive is sent by Ping++:
// Retrieve signature in header
$signature = $headers['X-Pingplusplus-Signature'] ?: null;
// Get the Ping++ RSA Public Key in Dashboard
$pub_key_contents = file_get_contents(__DIR__ . "/pingpp_rsa_public_key.pem");
if (openssl_verify(file_get_contents('php://input'), base64_decode($signature), $pub_key_contents, 'sha256')) {
// Congrats! This request is from Ping++
exit;
}
http_response_code(400);
The minimum integration for PC payment is simple, first you need to load pingpp.js , then test with code below:
<div class="app">
<label><input id="amount" type="text" placeholder="金 额"/></label>
<span class="up" onclick="wap_pay('upacp_pc')">银联网页支付</span>
<span class="up" onclick="wap_pay('alipay_pc_direct')">支付宝网页支付</span>
<span class="up" onclick="wap_pay('cp_b2b')">企业网银支付</span>
</div>
<script>
function wap_pay(channel) {
var amount = document.getElementById('amount').value * 100;
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://localhost:8000/test.php", true);
xhr.setRequestHeader("Content-type", "application/json");
xhr.send(JSON.stringify({
channel: channel,
amount: amount
}));
xhr.onreadystatechange = function () {
if (xhr.readyState == 4 && xhr.status == 200) {
console.log(xhr.responseText);
pingppPc.createPayment(xhr.responseText, function(result, err) {
console.log(result);
console.log(err.msg);
console.log(err.extra);
});
}
}
}
</script>
Pingpp accounts have test-mode API keys as well as live-mode API keys. These keys can be active at the same time. Data created with test-mode credentials will never hit the real payment channel networks and will never cost anyone money.
Unlike some gateways, there is no test mode endpoint separate to the live mode endpoint, the Pingpp API endpoint is the same for test and for live.
Yes. It's 100% compatible with official API.
transactionId
is the Merchant’s reference to the transaction - so typically the ID of the payment record in the Merchant Site’s database. In Ping++, it's often called order_no
.transactionReference
is the Payment Gateway’s reference to the transaction. In Ping++, it's often called Charge Id
, Red Envelope Id
, Transfer Id
.returnUrl
is used by drivers when they need to tell the Payment Gateway where to redirect the customer following a transaction. Typically this is used by off-site ‘redirect’ gateway integrations. In Ping++, it's called differently by various payment channels.notifyUrl
is used by drivers to tell the Payment Gateway where to send their server-to-server notification, informing the Merchant Site about the outcome of a transaction. In Ping++, it's called differently by various payment channels.If you are having general issues with Omnipay, we suggest posting on Stack Overflow. Be sure to add the omnipay tag so it can be easily found.
If you believe you have found a bug, please report it using the GitHub issue tracker, or better yet, fork the library and submit a pull request.