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_iv5yr1HWLOqHjbjTq1KWLmD4';
$appId = 'app_9SSaPOaDuPCKvHSy';
/**
* 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();
}
/**
* @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\FetchTransactionListRequest $transactionList
*/
$transactionList = $gateway->fetchTransactionList(array(
'appId' => $appId,
'channel' => Channels::ALIPAY,
'paid' => 0,
'refunded' => 0,
'createdFrom' => 1481116461,
'createdTo' => 1477723630,
'limit' => 2,
));
$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' => 2,
));
$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' => 2,
));
$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' => 2,
));
$response = $redEnvelopeList->send();
/**
* @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' => 2,
));
$response = $transferList->send();
/**
* @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.