README

GuavaPay电子商务SDK for PHP让开发者能够轻松将GuavaPay电子支付网关集成到他们的PHP代码中。您可以通过通过Composer安装SDK来在几分钟内开始使用。

跳转到

入门
示例

入门

注册GuavaPay – 要开始，首先您需要注册GuavaPay商户账户并获取您的凭证。
最低要求 – 运行SDK，您的系统需要满足最低要求，包括拥有 PHP >= 8.0。我们强烈建议使用编译了cURL扩展的PHP。
安装SDK – 使用composer是推荐的方式来安装SDK到您的应用程序中。SDK可通过Packagist获得。如果已安装Composer，您可以在项目的基本目录中运行以下命令以将SDK作为依赖项添加
```
composer require guavapay/epg
```
使用SDK – 最好的了解如何使用SDK的方式是阅读用户指南。示例部分将帮助您熟悉基本概念。

快速示例

创建EPG实例

<?php
require_once('./vendor/autoload.php');

use GuavaPay\EPG;

$epg = new EPG('USER', 'SECRET', 'BANK_ID', 'SERVICE_ID');

初始化EPG对象的实例后，您可以轻松调用方法。以下是一些示例。

在EPG上注册订单

为了接受支付，在电子支付网关（EPG）上注册订单是必要的。这可以通过从SDK中调用createOrder()方法来完成。

...
use GuavaPay\Exception\GuavaEcomException;
use GuavaPay\Exception\GuavaClientException;

try {
    $orderId = '123456'; // The order ID from your database.
    $amount = 100; // The amount in cents for the payment.
    $currency = 978; // The currency code in ISO 4217 format (Euro in this case).
    $returnUrl = 'http://example.com/paymentResult'; // The URL where the customer will be redirected after a successful payment.
    
    // Create an order using the Electronic Payment Gateway (EPG).
    $order = $epg->createOrder($orderId, $amount, $currency, $returnUrl); 
    
    // Get the EPG order ID for reference. Example: 84c5387a-7824-742b-9567-0c1a0e7e1e23.
    var_dump($order->getOrderId()); 

    // Get the URL for the payment, where the customer should be redirected to make the payment.
    var_dump($order->getFormUrl()); 

} catch (GuavaEcomException $e) { 
    // An error occurred due to a logical issue during the payment process.
    echo $e->getMessage();
} catch (GuavaClientException $e) { 
    // Unable to send the request to the EPG server, possibly due to connectivity issues.
    echo $e->getMessage();
}

从EPG获取订单状态

为了验证您的订单在电子支付网关（EPG）上的状态，您可以使用SDK中的getOrderStatus()方法。要访问EPG订单状态，您需要提供在GuavaPay集成过程中收到的状态码。

...
use GuavaPay\Exception\GuavaEcomException;
use GuavaPay\Exception\GuavaClientException;

try {
    $epgOrder = '84c5387a-7824-742b-9567-0c1a0e7e1e23'; // EPG order ID
    $statusCode = '013'; // status code which was provided by GuavaPay during the integration
    $orderInfo = $epg->getOrderStatus($epgOrder, $statusCode);
    var_dump($orderInfo->getStatus(), $orderInfo->getIsSuccess(), $orderInfo->getAmount());
} catch (GuavaEcomException $e) { 
    // An error occurred due to a logical issue during the payment process.
    echo $e->getMessage();
} catch (GuavaClientException $e) { 
    // Unable to send the request to the EPG server, possibly due to connectivity issues.
    echo $e->getMessage();
}

获取3D Secure版本

为了检查客户卡上的3D secure版本，您需要从SDK中调用check3dsVersion()方法，传入之前创建的EPG订单ID和其中的CardConfig对象。

...
use GuavaPay\Exception\GuavaEcomException;
use GuavaPay\Exception\GuavaClientException;
use GuavaPay\Config\CardConfig;

try {
    $epgOrder = '84c5387a-7824-742b-9567-0c1a0e7e1e23'; // EPG order ID
    $expiry = DateTime::createFromFormat('m/Y', '02/2030');
    $cardConfig = new CardConfig('CardNumber', $expiry, '547', 'CARD HOLDER');

    var_dump($epg->check3dsVersion($epgOrder, $cardConfig)->getVersion()); // int(2)
} catch (GuavaEcomException $e) { 
    // An error occurred due to a logical issue during the payment process.
    echo $e->getMessage();
} catch (GuavaClientException $e) { 
    // Unable to send the request to the EPG server, possibly due to connectivity issues.
    echo $e->getMessage();
}

支付

为了向客户的卡收费，首先您需要调用（如上所示）check3dsVersion()方法，然后从SDK中调用paymentRequest()方法，并传入其中的CardConfig和DeviceConfig对象。

...
use GuavaPay\Exception\GuavaEcomException;
use GuavaPay\Exception\GuavaClientException;
use GuavaPay\Config\CardConfig;
use GuavaPay\Config\DeviceConfig;

try {
    $expiry = DateTime::createFromFormat('m/Y', '02/2030');
    $cardConfig = new CardConfig('CardNumber', $expiry, '547', 'CARD HOLDER');
    $deviceConfig = new DeviceConfig(true, 'ru-RU', 986, 1024, 0, false, 16);
    $payment = $epg->paymentRequest('84c5387a-7824-742b-9567-0c1a0e7e1e23', $cardConfig, $deviceConfig);

} catch (GuavaEcomException $e) { 
    // An error occurred due to a logical issue during the payment process.
    echo $e->getMessage();
} catch (GuavaClientException $e) { 
    // Unable to send the request to the EPG server, possibly due to connectivity issues.
    echo $e->getMessage();
}

获取商户可用余额

为了检查您的商户账户上的可用资金，您需要使用在GuavaPay集成过程中提供的状态码，从SDK中调用getBalanceStatus()方法。

...
use GuavaPay\Exception\GuavaEcomException;
use GuavaPay\Exception\GuavaClientException;

try {
    var_dump($epg->getBalanceStatus(978, '013')->getAmount()); // returns float(133.74)
} catch (GuavaEcomException $e) { 
    // An error occurred due to a logical issue during the payment process.
    echo $e->getMessage();
} catch (GuavaClientException $e) { 
    // Unable to send the request to the EPG server, possibly due to connectivity issues.
    echo $e->getMessage();
}

检查回调签名

为了检查回调请求的签名，您需要从SDK中调用checkSignature()方法。

...
use GuavaPay\Exception\GuavaSignatureException;

try {
    $request = json_decode(file_get_contents('php://input'), true); // get JSON as PHP array from POST request
    if ($request === null && json_last_error() !== JSON_ERROR_NONE) {
        throw new Exception('Invalid JSON request');
    }
    $certPath = "file://./certificate.pem"; // path to your certificate file (.pem) from GuavaPay
    $publicKey = openssl_pkey_get_public($certPath);
    if ($publicKey === false) {
        throw new Exception('Invalid public key'); // if you have an error here, check your certificate file
    }
    $result = $epg->checkSignature($request, $request['signature'], $publicKey);
    echo 'Valid signature!'; // if you see this message, then the signature is valid

    // now you can top up the user's balance, update the order status, etc.
} catch (GuavaSignatureException $e) {
    echo 'Invalid signature!' . $e->getMessage(); // if you see this message, then the signature is invalid
} catch (\Exception $e) {
    echo $e->getMessage() . PHP_EOL; // if you see this message, then an error occurred
}

guavapay / epg

维护者

详细信息