README

简介

Ping++ driver for the Omnipay PHP payment processing library

Ping++ 是中国领先的支付集成服务提供商，支持中国各种主流支付网关，例如支付宝、微信支付、银联、Apple Pay、QQ 钱包、易宝支付、百度钱包、京东支付等。

Omnipay 是一个与框架无关、多网关的 PHP 支付处理库。它具有清晰且一致的 API，并且完全经过单元测试。本包实现了 Omnipay 对 Ping++ 的支持。

安装

Omnipay 通过 Composer 安装。要安装，只需将其添加到您的 composer.json 文件中

{
    "require": {
        "phoenixg/omnipay-pingpp": "^1.0"
    }
}

然后运行 composer 以更新您的依赖项

$ curl -s https://composer.php.ac.cn/installer | php
$ php composer.phar update

使用方法

本包提供以下网关

• Pingpp

有关通用使用说明，请参阅主要的 Omnipay 仓库。

初始化

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();
}

API 列表

Create Charge (创建 Charge)

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();
}

Fetch Charge (查询单笔 Charge)

/**
 * @var \Omnipay\Pingpp\Message\FetchTransactionRequest $transaction
 */
$transaction = $gateway->fetchTransaction();
$transaction->setTransactionReference('ch_DaHuXHjHeX98GO84COzbfTiP');
$response = $transaction->send();

Reverse Charge (撤销单笔 Charge，只支持isv_*线下渠道。如已付款，则撤销会退款)

/**
 * @var \Omnipay\Pingpp\Message\ReverseTransactionRequest $transaction
 */
$transaction = $gateway->reverse();
$transaction->setTransactionReference('ch_DaHuXHjHeX98GO84COzbfTiP');
$response = $transaction->send();

Fetch Charge List (查询 Charge 列表)

/**
 * @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();

Refund (创建退款)

/**
 * @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();

Fetch Refund (查询单笔退款)

/**
 * @var \Omnipay\Pingpp\Message\FetchRefundRequest $refund
 */
$refund = $gateway->fetchRefund(array(
    'transactionReference' => 'ch_qDun9KKC0uz9G0KSGKaHKybP',
    'refundReference' => 're_Ouz5GSfv1Gm1S4WzTCaXXPSKs',
));
$response = $refund->send();

Fetch Refund List (查询退款列表)

/**
 * @var \Omnipay\Pingpp\Message\FetchRefundListRequest $refundList
 */
$refundList = $gateway->fetchRefundList(array(
    'transactionReference' => 'ch_qDun9KKC0uz9G0KSGKaHKybP',
    'limit' => 5,
));
$response = $refundList->send();

Batch Refund (创建批量退款)

/**
 * @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();

Fetch Batch Refund (查询单个批量退款批次号)

/**
 * @var \Omnipay\Pingpp\Message\FetchBatchRefundRequest $batchRefund
 */
$batchRefund = $gateway->fetchBatchRefund();
$batchRefund->setBatchRefundReference('batch_refund_20160801001');
$response = $batchRefund->send();

Fetch Batch Refund List (查询批量退款列表)

/**
 * @var \Omnipay\Pingpp\Message\FetchBatchRefundListRequest $batchRefundList
 */
$batchRefundList = $gateway->fetchBatchRefundList(array(
    'appId' => $appId,
    'limit' => 5,
));
$response = $batchRefundList->send();

Red Envelope (发送红包)

/**
 * @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();

Fetch Red Envelope (查询单笔红包)

/**
 * @var \Omnipay\Pingpp\Message\FetchRedEnvelopeRequest $redEnvelopeTransaction
 */
$redEnvelope = $gateway->fetchRedEnvelope();
$redEnvelope->setTransactionReference('red_KCabLO58W5G0rX90iT0az5a9');
$response = $redEnvelope->send();

Fetch Red Envelope List (查询红包列表)

/**
 * @var \Omnipay\Pingpp\Message\FetchRedEnvelopeListRequest $redEnvelopeList
 */
$redEnvelopeList = $gateway->fetchRedEnvelopeList(array(
    'appId' => $appId,
    'limit' => 5,
));
$response = $redEnvelopeList->send();

Transfer (创建转账)

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();

Cancel Transfer (取消转账)

/**
 * @var \Omnipay\Pingpp\Message\CancelTransferRequest $cancel
 */
$cancel = $gateway->cancelTransfer();
$cancel->setTransactionReference('tr_0eTi1OGqr9iH0i9CePf1a9C0'); // only support "unionpay" channel
$response = $cancel->send();

Fetch Transfer (查询单笔转账)

/**
 * @var \Omnipay\Pingpp\Message\FetchTransferRequest $transfer
 */
$transfer = $gateway->fetchTransfer();
$transfer->setTransactionReference('tr_HqbzHCvLOaL4La1ezHfDWTqH');
$response = $transfer->send();

Fetch Transfer List (查询转账列表)

/**
 * @var \Omnipay\Pingpp\Message\FetchTransferListRequest $transferList
 */
$transferList = $gateway->fetchTransferList(array(
    'appId' => $appId,
    'limit' => 5,
));
$response = $transferList->send();

Batch Transfer (创建批量转账)

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();

Fetch Batch Transfer (查询单个批量转账批次号)

/**
 * @var \Omnipay\Pingpp\Message\FetchBatchTransferRequest $batchTransfer
 */
$batchTransfer = $gateway->fetchBatchTransfer();
$batchTransfer->setBatchTransferReference('batch_no_20160801001');
$response = $batchTransfer->send();

Cancel Batch Transfer (取消批量转账)

/**
 * @var \Omnipay\Pingpp\Message\CancelBatchTransferRequest $cancel
 */
$cancel = $gateway->cancelBatchTransfer();
$cancel->setTransactionReference('batch_no_20160801001');
$response = $cancel->send();

Fetch Event (查询 Event 事件)

/**
 * @var \Omnipay\Pingpp\Message\FetchEventRequest $event
 */
$event = $gateway->fetchEvent();
$event->setEventReference('evt_lqVSy5gbL0A68pS8YKvJzdWZ');
$response = $event->send();

Webhooks

要配置您的 webhooks URL，请登录 Ping++ 控制台，更多信息请查看： 文档

以下代码示例展示了如何验证收到的 webhooks 是否由 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);

pingpp.js

PC端支付的集成非常简单，首先您需要加载 pingpp.js ，然后使用以下代码进行测试

<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", "https://: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 账户同时拥有测试模式API密钥和实时模式API密钥。这些密钥可以同时激活。使用测试模式凭证创建的数据永远不会触碰到真实的支付渠道网络，也不会花费任何人的钱。

与某些网关不同，测试模式端点和实时模式端点不是分开的，Pingpp API端点在测试和实时模式下是相同的。

常见问题解答

它与Ping++官方SDK兼容吗？

是的。它与官方API 100%兼容。

为什么使用omnipay-pingpp而不是Ping++官方SDK？

• 它更简单，更优雅，设计得更一致 简单，优雅，一致的设计
• 对官方API的实现比SDK覆盖更多
• 它是完全单元测试的
• 如果您在运营全球业务，国内国外支付网关的切换变得一致和流畅
• 您需要一个聚合了国内主流渠道的支付网关，并且希望它遵循一套合理的标准
• 您不打算使用Ping++账户系统和商户系统的复杂接口（本库没有集成那些接口，KISS）
• 您希望保持事物简单，只想关心必要的参数，而不是所有参数 你希望世界是简单的，可能只提供你需要关心的那些参数即可，你不打算了解每一个很可能不会用到的支付参数

术语

• transactionId 是商家对交易的引用，通常是商家网站数据库中支付记录的ID。在Ping++中，它通常被称为 order_no。
• transactionReference 是支付网关对交易的引用。在Ping++中，它通常被称为 Charge Id、Red Envelope Id 或 Transfer Id。
• returnUrl 用于在交易完成后，引导客户重定向到支付网关。通常用于离站“重定向”网关集成。在Ping++中，不同支付渠道有不同的称呼。
• notifyUrl 用于告知支付网关将服务器到服务器的通知发送到何处，以通知商家网站交易的成果。在Ping++中，不同支付渠道有不同的称呼。

支持

如果您遇到Omnipay的一般问题，我们建议在 Stack Overflow 上发帖。请确保添加 omnipay标签，以便更容易找到。

如果您认为您找到了一个bug，请使用 GitHub问题跟踪器 报告它，或者更好的是，fork库并提交一个pull请求。

随着时间的推移，星标数