README

💰 用于与 Comgate 进行通信的 PHP 库。

入门指南

安装

要安装最新版本的 comgate/sdk，请使用 Composer。

composer require comgate/sdk

您必须在您的 PHP 服务器上安装 php-xml 扩展（例如：Ubuntu：apt-get install php-xml）。

文档

https://help.comgate.cz/docs/protocol-api-en（英文版本）
https://help.comgate.cz/docs/api-protokol（捷克语版本）

注册

首先在我们的网站上注册您的账户 comgate.cz。
您将获得 商户标识符 和密钥。
在 portal.comgate.cz 上允许您的电商服务器 IPv4 地址。
在 portal.comgate.cz 上设置 PAID、CANCELLED、PENDING 和 STATUS URL。

设置客户端

use Comgate\SDK\Comgate;

$client = Comgate::defaults()
    ->setMerchant('123456') // get on portal.comgate.cz
    ->setSecret('foobarbaz') // get on portal.comgate.cz
    ->createClient();

创建支付

use Comgate\SDK\Entity\Codes\CategoryCode;
use Comgate\SDK\Entity\Codes\CurrencyCode;
use Comgate\SDK\Entity\Codes\DeliveryCode;
use Comgate\SDK\Entity\Codes\PaymentMethodCode;
use Comgate\SDK\Entity\Money;
use Comgate\SDK\Entity\Payment;
use Comgate\SDK\Utils\Helpers;
use Comgate\SDK\Entity\Codes\RequestCode;
use Comgate\SDK\Exception\ApiException;

$payment = new Payment();
$payment
    ->setPrice(Money::ofInt(50)) // 50 CZK
    ->setPrice(Money::ofFloat(50.25)) // 50,25 CZK
    ->setPrice(Money::ofCents(5025)) // 50,25 CZK
    // -----
    ->setCurrency(CurrencyCode::CZK)
    ->setLabel('Test item')
    // or ->setParam('label', 'Test item') // you can pass all params like this
    ->setReferenceId('test001')
    ->setEmail('foo@bar.tld')
    ->addMethod(PaymentMethodCode::ALL)
    //->setRedirect()
    //->setIframe()
    ->setTest(false)
    ->setFullName('Jan Novák')
    ->setCategory(CategoryCode::PHYSICAL_GOODS_ONLY)
    ->setDelivery(DeliveryCode::HOME_DELIVERY);


try {
    $createPaymentResponse = $client->createPayment($payment);
    if ($createPaymentResponse->getCode() === RequestCode::OK) {
        // Redirect the payer to Comgate payment gateway (use proper method of your framework)
        Helpers::redirect($createPaymentResponse->getRedirect());
    } else {
        var_dump($createPaymentResponse->getMessage());
    }
} catch (ApiException $e) {
    var_dump($e->getMessage());
}

$client->createPayment 的成功响应示例。

$transactionId = $createPaymentResponse->getTransId(); // XXXX-YYYY-ZZZZ
$code = $createPaymentResponse->getCode(); // 0
$message = $createPaymentResponse->getMessage(); // OK
$redirect = $createPaymentResponse->getRedirect(); // https://payments.comgate.cz/client/instructions/index?id=XXXX-YYYY-ZZZZ

$client->createPayment 的错误响应示例。

$code = $e->getCode(); // 1109
$message = $e->getMessage(); // Invalid payment method [fake]

获取方法

use Comgate\SDK\Exception\ApiException;

try {
    $methodsResponse = $client->getMethods();
    foreach ($methodsResponse->getMethodsList() as $method) {
        var_dump([
            $method->getId(),
            $method->getName(),
            $method->getDescription(),
            $method->getLogo(),
        ]);
    }
} catch (ApiException $e) {
    var_dump($e->getMessage());
}

完成订单并向返回的付款人显示支付状态

示例 PAID URL: https://your-eshop.tld/order-finish.php?id=${id}&refId=${refId}&status=PAID
示例 PAID CANCELLED: https://your-eshop.tld/order-finish.php?id=${id}&refId=${refId}&status=CANCELLED
示例 PAID PENDING: https://your-eshop.tld/order-finish.php?id=${id}&refId=${refId}&status=PENDING

use Comgate\SDK\Entity\Payment;
use Comgate\SDK\Entity\PaymentNotification;
use Comgate\SDK\Entity\Codes\PaymentStatusCode;

$transactionId = $_GET['id']; // XXXX-YYYY-ZZZZ
$refId = $_GET['refId']; // your order number

try {
    $paymentStatusResponse = $client->getStatus($transactionId);

    switch ($paymentStatusResponse->getStatus()){
        case PaymentStatusCode::PAID:
            // Your code (set order as paid)
            echo "Your payment was PAID successfully.";
            break;

        case PaymentStatusCode::CANCELLED:
            // Your code (set order as cancelled)
            echo "Your order was CANCELLED.";
            break;

        case PaymentStatusCode::PENDING:
            // Your code (order is still pending)
            echo "We are waiting for the payment.";
            break;

        case PaymentStatusCode::AUTHORIZED:
            // Your code (set order as authorized)
            echo "Payment was authorized successfully.";
            break;
    }
} catch (ApiException $e) {
    var_dump($e->getMessage());
}

接收支付通知（服务器到服务器）

示例 URL: https://your-eshop.tld/notify.php

use Comgate\SDK\Entity\PaymentNotification;
use Comgate\SDK\Entity\Codes\PaymentStatusCode;
use Comgate\SDK\Exception\ApiException;

// Create from $_POST global variable
// $notification = PaymentNotification::createFromGlobals();

// Create from your framework
$data = $framework->getHttpRequest()->getPostData();
$notification = PaymentNotification::createFrom($data);
$transactionId = $notification->getTransactionId();

try {
    // it's important to check the status from API
    $paymentStatusResponse = $client->getStatus($transactionId);

    switch ($paymentStatusResponse->getStatus()){
        case PaymentStatusCode::PAID:
            // Your code (set order as paid)
            break;

        case PaymentStatusCode::CANCELLED:
            // Your code (set order as cancelled)
            break;

        case PaymentStatusCode::AUTHORIZED:
            // Your code (set order as authorized)
            break;

        // PaymentStatusCode::PENDING - is NOT send via push notification
    }

    echo "OK"; // important response with HTTP code 200

} catch (ApiException $e) {
    var_dump($e->getMessage());
}

创建退款

use Comgate\SDK\Entity\Refund;
use Comgate\SDK\Exception\ApiException;
use Comgate\SDK\Entity\Money;
use Comgate\SDK\Entity\Codes\RequestCode;

$refund = new Refund();
$refund->setTransId('XXXX-YYYY-ZZZZ')
    ->setAmount(Money::ofCents(100))
    ->setRefId('11bb22');

try{
    $refundResult = $client->refundPayment($refund);
    if($refundResult->getCode() == RequestCode::OK) {
        // refund created successfully
    }
} catch (ApiException $e){
    var_dump($e->getMessage());
}

调试

日志记录

我们使用 PSR-3 进行日志记录。

use Comgate\SDK\Comgate;
use Comgate\SDK\Logging\FileLogger;
use Comgate\SDK\Logging\StdoutLogger;


$client = Comgate::defaults()
    ->setLogger(new FileLogger(__DIR__ . '/comgate.log'))
    ->createClient();

查看我们的测试以了解日志记录器格式。

维护

如果您发现一个错误，请直接在 Github 中提交问题。

感谢您使用我们的 Comgate 支付。

comgate / sdk

维护者

详细信息