cardpay/php-sdk

此包已被废弃且不再维护。未建议替代包。
此包的最新版本（2.1.1）没有可用的许可证信息。

CardPay PHP SDK

维护者

详细信息

github.com/cardpay/php-sdk

主页

源代码

问题

安装量: 44,548

依赖项: 0

建议者: 0

安全: 0

星标: 6

关注者: 5

分支: 4

公开问题: 0

类型:sdk

2.1.1 2018-07-31 13:20 UTC

Requires

  • php: >=5.6

Requires (Dev)

Unknown License b1242196492f21542926e40aa43c87ebbf0ba40a

  • Evgenii Panov <e.panov.woop@cy.cardpay.com>

phpsdkcardpay

This package is not auto-updated.

Last update: 2020-01-28 11:22:31 UTC

README

请使用Cardpay API v3的PHP SDK代替。

CardPay API的PHP SDK

API文档

先决条件

  • PHP 5.6或更高版本
  • curl，xml
  • 必须启用openssl扩展才能使用网关模式

安装

使用composer

composer require cardpay/php-sdk:@stable

用法

目录

  1. 配置
  2. 支付页面模式
    1. 简单支付
    2. 授权支付
    3. 周期性支付
    4. 使用令牌支付
    5. 获取orderXML和SHA512
    6. 添加收货地址
    7. 添加购物车项目
  3. 网关模式
    1. 简单支付
    2. 授权支付
    3. 周期性支付
    4. 使用令牌支付
    5. 获取orderXML和SHA512
    6. 添加收货地址
    7. 添加账单地址
    8. 添加购物车项目
  4. 回调
  5. 更改订单状态
    1. 捕获授权支付
    2. 撤销授权支付
    3. 退款
  6. 支付报告
    1. 获取支付列表
    2. 支付状态
  7. 退款报告
    1. 获取退款列表
    2. 退款状态

1. 配置

~$ vim config.php
<?php

use \CardPay\Core\CardPayConfig;

return (new CardPayConfig(CardPayMode::TEST))
    ->setWalletId(1234)
    ->setSecretKey('YourSecretWord')
    ->setClientLogin("YourLoginForPaymentManager")
    ->setClientPasswordSHA256("YourPasswordForPaymentManagerEncodedWithSHA256")
    ->setRestApiLogin("YourLoginForUsingRestApi")
    ->setRestApiPassword("YourPasswordForUsingRestApi")
    ->setLogFilepath(__DIR__.'/cardpay.log');

2. 支付页面模式

支付页面模式用于商家选择使用我们的支付页面时。客户将从商家的网站重定向到我们的支付页面输入卡信息。客户在我们支付页面上输入的数据受到CardPay的保护和管理，并符合PCI DSS标准。所有客户数据都通过安全连接发送。

2.1. 简单支付

<?php

use \CardPay\Core\CardPayPaymentPageMode;
use CardPay\Exception\CardPayLoggerException;
use CardPay\Log\CardPayLogger;

try {
    $config = require_once(__DIR__ . "/config.php");

    $cardPayPaymentPageMode = new CardPayPaymentPageMode();

    $cardPayPaymentPageMode
        ->setConfig($config)
        ->setOrderId("1234567890")
        ->setDescription("Payment description")
        ->setCurrency("USD")
        ->setAmount(100)
        ->setEmail("payment@your-domain.com")
        ->setCustomerId('John Doe')
        ->setIsTwoPhase(false)
        ->setLocale("en")
        ->setNote("Payment note")
        ->setReturnUrl("https://www.your-domain.com/return_page.php");

    echo $cardPayPaymentPageMode->getSimpleForm();

    exit;
} catch (CardPayLoggerException $e) {
    exit("{$e->getMessage()} in {$e->getTraceAsString()}");
} catch (\Exception $e) {
    CardPayLogger::log($e->getMessage(), $e->getTraceAsString());
}

2.2. 授权支付

第一步

金额不会被扣款，只会被冻结。

...

    $cardPayPaymentPageMode
        ->setConfig($config)
        ->setOrderId("1234567890")
        ...
        ->setIsTwoPhase(true);

    echo $cardPayPaymentPageMode->getSimpleForm();

...
第二步

使用更改订单状态

2.3. 周期性支付

您可以通过发送具有“recurring_begin”属性且值为“true”的常规订单来开始循环支付，然后无需让持卡人再次输入卡信息，即可重复使用同一张卡进行支付。为此，您需要从支付结果XML中获取“recurring_id”属性的值，或者在支付管理器的“循环计费”部分中找到它。当您使用“recurring_id”继续循环支付时，因为使用的卡与开始循环时相同，所以不会显示支付页面。

第一步

可以使用响应中的recurring_id稍后重复支付。

...

    $cardPayPaymentPageMode
        ->setConfig($config)
        ->setOrderId("1234567890")
        ...
        ->setRecurringBegin(true);

    echo $cardPayPaymentPageMode->getSimpleForm();

...
第二步

之前已发送的重复支付。

...

    $cardPayPaymentPageMode
        ->setConfig($config)
        ->setOrderId("1234567890")
        ...
        ->setRecurringId(12345);

    echo $cardPayPaymentPageMode->getSimpleForm();

...

2.4. 使用令牌支付

卡令牌功能几乎与循环支付相同，但不同之处在于在这种情况下，每次支付都是在持卡人到场的情况下进行的，并且如果可用，则需要CVV2/CVC2和3-D Secure。您可以通过发送具有“generate_card_token”属性且值为“true”的常规订单来获取卡令牌。生成的卡令牌仅在回调中发送，并且仅在支付成功的情况下发送。每次请求令牌时，即使是对同一张卡，也会生成新的令牌。要使用卡令牌，您可以在“card_token”属性中发送它，这样客户就无需再次输入卡信息，只需CVV2/CVC2，如果需要，则通过3-D Secure。

第一步

卡令牌将在响应或通知XML中生成并返回。

...

    $cardPayPaymentPageMode
        ->setConfig($config)
        ->setOrderId("1234567890")
        ...
        ->setGenerateCardToken(true);

    echo $cardPayPaymentPageMode->getSimpleForm();

...
第二步

使用卡令牌代替卡信息。

...

    $cardPayPaymentPageMode
        ->setConfig($config)
        ->setOrderId("1234567890")
        ...
        ->setCardToken(123456789);

    echo $cardPayPaymentPageMode->getSimpleForm();

...

2.5. 获取orderXML和SHA512

...

    $cardPayPaymentPageMode
        ->setConfig($config)
        ->setOrderId("1234567890")
        ...

    $base64Encode = true;
    echo $cardPayPaymentPageMode->getOrderXML($base64Encode);
    
    echo $cardPayPaymentPageMode->getSHA512();

...

2.6. 添加收货地址

...

    $cardPayAddress = new CardPayAddress();
    $cardPayAddress
        ->setCountry("USA")
        ->setState("NY")
        ->setZip("1234")
        ->setCity("New York")
        ->setStreet("Central Park, Big tree, Second branch")
        ->setPhone("+11123455678");

    $cardPayPaymentPageMode->setShipping($cardPayAddress);

...

2.7. 添加购物车商品

...

    $cardPayItemOne = new CardPayItem();
    $cardPayItemOne
        ->setName("Product 1")
        ->setDescription("Best product 1")
        ->setCount(2)
        ->setPrice("10.11");

    $cardPayItemTwo = new CardPayItem();
    $cardPayItemTwo
        ->setName("Product 2")
        ->setDescription("Best product 2")
        ->setCount(3)
        ->setPrice("20.11");

    $cardPayItemThree = new CardPayItem();
    $cardPayItemThree
        ->setName("Product 3")
        ->setDescription("Best product 3")
        ->setCount(1)
        ->setPrice("30.11");

    $cardPayPaymentPageMode->setItems([
        $cardPayItemOne,
        $cardPayItemTwo,
        $cardPayItemThree,
    ]);

...

示例

vim .sample/paymentPageMode.php

3. 网关模式

在网关模式下，客户在商户网站上输入信用卡数据，订单从商户发送到CardPay服务器。在这种情况下，商户必须在网站上收集持卡人数据，并且该网站必须通过PCI DSS认证，然后将它作为POST请求发送到CardPay支付端点。

作为对商户请求的响应，CardPay服务器会发送客户应该被重定向到的URL。当支付完成后，客户将被重定向回商店的预定义URL之一。此外，还将发送回调和/或电子邮件通知。

3.1. 简单支付

<?php

use CardPay\Core\CardPayCard;
use CardPay\Core\CardPayGatewayMode;
use CardPay\Exception\CardPayLoggerException;
use CardPay\Log\CardPayLogger;

try {
    $config = require_once(__DIR__ . "/config.php");

    $cardPayGatewayMode = new CardPayGatewayMode();
    $cardPayGatewayMode
        ->setConfig($config);
        ->setOrderId("1234567890")
        ->setDescription("Payment description")
        ->setCurrency("USD")
        ->setAmount(100)
        ->setEmail("payment@your-domain.com")
        ->setCustomerId("John Doe")
        ->setIsTwoPhase(false)
        ->setNote("Payment note")
        ->setReturnUrl("https://www.your-domain.com/return_page.php");

    $cardPayCard = new CardPayCard();
    $cardPayCard
        ->setCardNumber("4000000000000077")
        ->setCardholderName("John Doe")
        ->setExpirationDate(
            "2025",
            "12")
        ->setCvc("123");

    $cardPayGatewayMode->setCard($cardPayCard);

    $cardPayGatewayMode
        ->sendRequest()
        ->parseResponse();

    header("Location: " . $cardPayGatewayMode->getRedirectUrl());

    exit;
} catch (CardPayLoggerException $e) {
    exit("{$e->getMessage()} in {$e->getTraceAsString()}");
} catch (\Exception $e) {
    CardPayLogger::log($e->getMessage(), $e->getTraceAsString());
}

3.2. 授权支付

第一步

金额不会被扣款，只会被冻结。

...

    $cardPayGatewayMode
        ->setOrderId("1234567890")
        ...
        ->setIsTwoPhase(true);

    $cardPayGatewayMode
        ->sendRequest()
        ->parseResponse();

    header("Location: " . $cardPayGatewayMode->getRedirectUrl());

...
第二步

使用更改订单状态

3.3. 循环支付

您可以通过发送带有“recurring_begin”属性且值为“true”的常规订单来开始周期性支付，然后无需让持卡人再次输入卡信息，即可使用同一张卡重复付款。为此，您需要从支付结果XML中获取“recurring_id”属性的值，或者在支付管理器的“周期性账单”部分中找到它。当您使用“recurring_id”继续周期性支付时，可以省略orderXML中的“order/card”标签，因为使用的卡与开始周期性支付时相同。此外，在周期性支付中，不再使用重定向XML，而是将支付结果XML作为响应发送。

第1步

可以使用响应中的recurring_id稍后重复支付。

...

    $cardPayGatewayMode
        ->setOrderId("1234567890")
        ...
        ->setRecurringBegin(true);

    $cardPayGatewayMode
        ->sendRequest()
        ->parseResponse();

    header("Location: " . $cardPayGatewayMode->getRedirectUrl());

...
第2步

之前已发送的重复支付。

...

    $cardPayGatewayMode
        ->setOrderId("1234567890")
        ...
        ->setRecurringId(12345);

    $cardPayGatewayMode
        ->sendRequest()
        ->parseResponse();

    header("Location: " . $cardPayGatewayMode->getRedirectUrl());

...

3.4. 使用令牌支付

卡令牌功能几乎与周期性支付相同，但不同之处在于在这种情况下，每次付款都要求持卡人现场进行，如果可用，则需要CVV2/CVC2和3-D Secure。您可以通过发送带有“generate_card_token”属性且值为“true”的常规订单来获取卡令牌。生成的卡令牌仅在回调中发送，并且仅在支付成功的情况下发送。每次请求令牌时，即使是同一张卡，也会生成一个新的令牌。要使用卡令牌，您可以在“card_token”属性中发送它，在这种情况下，“order/card”标签必须只包含“cvv”字段。

第1步

卡令牌将在响应或通知XML中生成并返回。

...

    $cardPayGatewayMode
        ->setOrderId("1234567890")
        ...
        ->setGenerateCardToken(true);

    $cardPayGatewayMode
        ->sendRequest()
        ->parseResponse();

    header("Location: " . $cardPayGatewayMode->getRedirectUrl());

...
第2步

使用卡令牌代替卡信息。

...

    $cardPayGatewayMode
        ->setOrderId("1234567890")
        ...
        ->setCardToken(123456789);

    $cardPayGatewayMode
        ->sendRequest()
        ->parseResponse();

    header("Location: " . $cardPayGatewayMode->getRedirectUrl());

...

3.5. 获取orderXML和SHA512

...

    $cardPayGatewayMode
        ->setOrderId("1234567890")
        ...

    $base64Encode = true;
    echo $cardPayGatewayMode->getOrderXML($base64Encode);
    
    echo $cardPayGatewayMode->getSHA512();

...

3.6. 添加收货地址

...

    $cardPayAddress = new CardPayAddress();
    $cardPayAddress
        ->setCountry("USA")
        ->setState("NY")
        ->setZip("1234")
        ->setCity("New York")
        ->setStreet("Central Park, Big tree, Second branch")
        ->setPhone("+11123455678");

    $cardPayGatewayMode->setShipping($cardPayAddress);

...

3.7. 添加账单地址

...

    $cardPayAddress = new CardPayAddress();
    $cardPayAddress
        ->setCountry("USA")
        ->setState("NY")
        ->setZip("1234")
        ->setCity("New York")
        ->setStreet("Central Park, Big tree, Second branch")
        ->setPhone("+11123455678");

    $cardPayGatewayMode->setBilling($cardPayAddress);

...

3.8. 添加购物车商品

...

    $cardPayItemOne = new CardPayItem();
    $cardPayItemOne
        ->setName("Product 1")
        ->setDescription("Best product 1")
        ->setCount(2)
        ->setPrice("10.11");

    $cardPayItemTwo = new CardPayItem();
    $cardPayItemTwo
        ->setName("Product 2")
        ->setDescription("Best product 2")
        ->setCount(3)
        ->setPrice("20.11");

    $cardPayItemThree = new CardPayItem();
    $cardPayItemThree
        ->setName("Product 3")
        ->setDescription("Best product 3")
        ->setCount(1)
        ->setPrice("30.11");

    $cardPayGatewayMode->setItems([
        $cardPayItemOne,
        $cardPayItemTwo,
        $cardPayItemThree,
    ]);

...
示例
~$ vim /sample/gatewayMode.php

4. 回调

交易处理完成后，支付结果XML将发送到商家提供的回调URL。只有CardPay经理可以设置或更改回调URL。

回调URL可能包含类似于返回URL的URL占位符，但请注意，设置到这些占位符的值未经摘要签名，不应用于做出决策，仅供优化使用。要更改订单状态，您需要在sha512摘要验证后从orderXML中获取状态、ID和其他字段。

回调总是在收到订单并更改状态后发送。如果未交付，则回调将重复。如果收到成功代码（200），则回调将被标记为已送达。您还可以在响应中打印一些固定文本（例如：“OK”），然后通知CardPay经理，只有当收到成功代码（200）和预期文本时，回调才被标记为已送达。

<?php

use \CardPay\Core\CardPayCallback;
use \CardPay\Log\CardPayLogger;

try {
    $config = require_once(__DIR__ . "/config.php");

    $cardPayCallback = new CardPayCallback();
    $cardPayCallback
        ->setConfig($config)
        ->setRequest($_REQUEST)
        ->parseRequest();

    switch (true) {
        case $cardPayCallback->isApproved():
            ...
            break;
        case $cardPayCallback->isPending():
            ...
            break;
        case $cardPayCallback->isDeclined():
        case $cardPayCallback->isVoided():
        case $cardPayCallback->isRefunded():
        case $cardPayCallback->isChargeback():
        case $cardPayCallback->isChargebackResolved():
            ...
            break;
    }

    header("HTTP/1.1 200 OK");

    echo "OK";
} catch (\Exception $e) {
    CardPayLogger::log($e->getMessage(), $e->getTraceAsString());

    header($_SERVER["SERVER_PROTOCOL"] . " 500 Internal Server Error", true, 500);
}

exit;
示例
~$ vim /sample/callback.php

5. 更改订单状态

此方法允许您更改订单状态。它允许捕捉两阶段交易、在可能的情况下取消交易或部分或全额退款。

认证

使用此服务，您需要支付管理员的用户登录和SHA-256十六进制编码的密码摘要。此服务仅影响此用户可修改的订单。

注意：强烈建议存储您的密码摘要。请不要为每次请求重新计算密码摘要！

5.1. 捕获授权支付

<?php

use CardPay\Core\CardPayChangeOrderStatus;
use CardPay\Exception\CardPayLoggerException;
use CardPay\Log\CardPayLogger;

try {
    $config = require_once(__DIR__ . "/config.php");

    $cardPayChangeOrderStatus = new CardPayChangeOrderStatus($config);

    $cardPayChangeOrderStatus
        ->setConfig($config)
        ->setOrderId("756013")
        ->setCaptureStatus();

    $cardPayChangeOrderStatus
        ->sendRequest()
        ->parseResponse();

    if ($cardPayChangeOrderStatus->isExecuted()) {
        ...
    } else {
        ...
        echo $cardPayChangeOrderStatus->getDetails();
    }

    exit;
} catch (CardPayLoggerException $e) {
    exit("{$e->getMessage()} in {$e->getTraceAsString()}");
} catch (\Exception $e) {
    CardPayLogger::log($e->getMessage(), $e->getTraceAsString());
}
示例
~$ vim /sample/changeOrderStatusCapture.php

5.2. 取消授权支付

...

    $cardPayChangeOrderStatus
        ->setConfig($config)
        ->setOrderId("756013")
        ->setVoidStatus();

    $cardPayChangeOrderStatus
        ->sendRequest()
        ->parseResponse();

    if ($cardPayChangeOrderStatus->isExecuted()) {
        ...
    } else {
        ...
        echo $cardPayChangeOrderStatus->getDetails();
    }
    
...
示例
~$ vim /sample/changeOrderStatusVoid.php

5.3. 退款支付

...

    $cardPayChangeOrderStatus
        ->setConfig($config)
        ->setOrderId("756529")
        ->setRefundStatus()
        ->setRefundReason("Out of stock");

    $cardPayChangeOrderStatus
        ->sendRequest()
        ->parseResponse();

    if ($cardPayChangeOrderStatus->isExecuted()) {
        ...
    } else {
        ...
        echo $cardPayChangeOrderStatus->getDetails();
    }
    
...
示例
~$ vim /sample/changeOrderStatusRefund.php

6. 支付报告

6.1. 获取支付列表

获取一段时间内的支付列表。此服务将仅返回此用户可查看的支付信息。

<?php

use CardPay\Core\CardPayPaymentsReport;
use CardPay\Core\CardPayTransaction;
use CardPay\Exception\CardPayLoggerException;
use CardPay\Log\CardPayLogger;

try {
    $config = require_once(__DIR__ . "/config.php");

    $cardPayPaymentsReport = new CardPayPaymentsReport();

    $cardPayPaymentsReport
        ->setConfig($config)
        ->setStartTimestampMilliseconds(strtotime("-7 days") . "000")
        ->setEndTimestampMilliseconds(time() . "000")
        //->setOrderId(123456789)
        ->setMaxCount(10000);

    $cardPayPaymentsReport
        ->sendRequest()
        ->parseResponse();

    $transactions = $cardPayPaymentsReport->getTransactions();

    /** @var CardPayTransaction $transaction */
    foreach ($transactions as $transaction) {
        switch (true) {
            case $transaction->isApproved():
                ...
                break;
            case $transaction->isInProgress():
            case $transaction->isPending():
                ...
                break;
            case $transaction->isDeclined():
            case $transaction->isVoided():
            case $transaction->isRefunded():
            case $transaction->isChargeback():
            case $transaction->isChargebackResolved():
                ...
                break;
        }
    }

    exit;
} catch (CardPayLoggerException $e) {
    exit("{$e->getMessage()} in {$e->getTraceAsString()}");
} catch (\Exception $e) {
    CardPayLogger::log($e->getMessage(), $e->getTraceAsString());
}
示例
~$ vim /sample/paymentsReport.php

6.2. 支付状态

使用此调用通过其ID获取支付状态。

<?php

use CardPay\Core\CardPayPaymentReport;
use CardPay\Exception\CardPayLoggerException;
use CardPay\Log\CardPayLogger;

try {
    $config = require_once(__DIR__ . "/config.php");

    $cardPayPaymentReport = new CardPayPaymentReport();

    $cardPayPaymentReport
        ->setConfig($config)
        ->setTransactionId(123456);

    $cardPayPaymentReport
        ->sendRequest()
        ->parseResponse();

    $transaction = $cardPayPaymentReport->getTransaction();

    switch (true) {
        case $transaction->isApproved():
            ...
            break;
        case $transaction->isInProgress():
        case $transaction->isPending():
            ...
            break;
        case $transaction->isDeclined():
        case $transaction->isVoided():
        case $transaction->isRefunded():
        case $transaction->isChargeback():
        case $transaction->isChargebackResolved():
            ...
            break;
    }

    exit;
} catch (CardPayLoggerException $e) {
    exit("{$e->getMessage()} in {$e->getTraceAsString()}");
} catch (\Exception $e) {
    CardPayLogger::log($e->getMessage(), $e->getTraceAsString());
}
示例
~$ vim /sample/paymentReport.php

7. 退款报告

7.1. 获取退款列表

获取一段时间内的退款列表。此服务将仅返回此用户可查看的退款信息。

<?php

use CardPay\Core\CardPayRefundsReport;
use CardPay\Core\CardPayTransaction;
use CardPay\Exception\CardPayLoggerException;
use CardPay\Log\CardPayLogger;

try {
    $config = require_once(__DIR__ . "/config.php");

    $cardPayRefundsReport = new CardPayRefundsReport();

    $cardPayRefundsReport
        ->setConfig($config)
        ->setStartTimestampMilliseconds(strtotime("-7 days") . "000")
        ->setEndTimestampMilliseconds(time() . "000")
        //->setOrderId(1489398769)
        ->setMaxCount(10000);

    $cardPayRefundsReport
        ->sendRequest()
        ->parseResponse();

    $transactions = $cardPayRefundsReport->getTransactions();

    foreach ($transactions as $transaction) {
        switch (true) {
            case $transaction->isApproved():
                ...
                break;
            case $transaction->isInProgress():
                ...
                break;
            case $transaction->isDeclined():
            case $transaction->isVoided():
                ...
                break;
        }
    }

    exit;
} catch (CardPayLoggerException $e) {
    exit("{$e->getMessage()} in {$e->getTraceAsString()}");
} catch (\Exception $e) {
    CardPayLogger::log($e->getMessage(), $e->getTraceAsString());
}
示例
~$ vim /sample/refundsReport.php

7.2. 退款状态

使用此调用通过其ID获取退款状态。

<?php

use CardPay\Core\CardPayRefundReport;
use CardPay\Exception\CardPayLoggerException;
use CardPay\Log\CardPayLogger;

try {
    $config = require_once(__DIR__ . "/config.php");

    $cardPayPaymentReport = new CardPayRefundReport();

    $cardPayPaymentReport
        ->setConfig($config)
        ->setTransactionId(123456);

    $cardPayPaymentReport
        ->sendRequest()
        ->parseResponse();

    $transaction = $cardPayPaymentReport->getTransaction();

    switch (true) {
        case $transaction->isApproved():
            ...
            break;
        case $transaction->isInProgress():
            ...
            break;
        case $transaction->isDeclined():
        case $transaction->isVoided():
            ...
            break;
    }

    exit;
} catch (CardPayLoggerException $e) {
    exit("{$e->getMessage()} in {$e->getTraceAsString()}");
} catch (\Exception $e) {
    CardPayLogger::log($e->getMessage(), $e->getTraceAsString());
}
示例
~$ vim /sample/refundReport.php

单元测试

~$ composer update
~$ php ./vendor/bin/phpunit

更多帮助