README

这是当前 2Checkout PHP SDK，为开发者提供了一组简单的绑定，用于 2Checkout 6.0 REST API、IPN 和 Convert Plus Signature API。

使用时，请使用 composer 克隆并 require，或 require 包含的自动加载器。

require_once('/path/to/2checkout-php-library/autoloader.php');
use Tco\TwocheckoutFacade;

此库中所有功能都通过 TwocheckoutFacade 实例使用，该实例可以使用配置数组进行初始化。

$config    = array(
            'sellerId'      => YOUR_MERCHANT_CODE, // REQUIRED
            'secretKey'     => YOUR_SECRET_KEY, // REQUIRED
            'buyLinkSecretWord'    => YOUR_SECRET_WORD,
            'jwtExpireTime' => 30,
            'curlVerifySsl' => 1
);

$tco = new TwocheckoutFacade($config);

- > $config 中所有必需的参数都可以在 CPanel 中找到，在集成 -> Webhooks & API 部分。

直接使用 Api Core

如下调用任何 2Checkout REST 6.0 终端

$result = $tco->apiCore()->call( '/orders/', $params, 'POST' );

下订单助手

您还可以使用提供的 Order 助手对象。

动态产品

$dynamicOrderParams = array(
            'Country'           => 'US',
            'Currency'          => 'USD',
            'CustomerIP'        => '91.220.121.21',
            'ExternalReference' => 'CustOrd101',
            'Language'          => 'en',
            'Source'            => 'tcolib.local',
            'BillingDetails'    =>
                array(
                    'Address1'    => 'Street 1',
                    'City'        => 'Cleveland',
                    'State'       => 'Ohio',
                    'CountryCode' => 'US',
                    'Email'       => 'testcustomer@2Checkout.com',
                    'FirstName'   => 'John',
                    'LastName'    => 'Doe',
                    'Zip'         => '20034',
                ),
            'Items'             =>
                array(
                    0 =>
                        array(
                            'Name'         => 'Dynamic product2',
                            'Description'  => 'Product 2',
                            'Quantity'     => 3, //units
                            'IsDynamic'    => true,
                            'Tangible'     => false,
                            'PurchaseType' => 'PRODUCT',
                            'Price'        =>
                                array(
                                    'Amount' => 6, //value
                                    'Type'   => 'CUSTOM',
                                ),
                        ),
                    1 =>
                        array(
                            'Name'         => 'Dynamic product',
                            'Description'  => 'Test description',
                            'Quantity'     => 4,
                            'IsDynamic'    => true,
                            'Tangible'     => false,
                            'PurchaseType' => 'PRODUCT',
                            'Price'        =>
                                array(
                                    'Amount' => 1,
                                    'Type'   => 'CUSTOM',
                                )
                        ),
                ),
            'PaymentDetails'    =>
                array(
                    'Type'          => 'TEST', //'TEST' or 'EES_TOKEN_PAYMENT'
                    'Currency'      => 'USD',
                    'CustomerIP'    => '91.220.121.21',
                    'PaymentMethod' =>
                        array(
                            'RecurringEnabled' => false,
                            'HolderNameTime'   => 1,
                            'CardNumberTime'   => 1,
                        ),
                ),
        );

通过调用 TwocheckoutFacade 的 "order()" 方法，我们可以通过调用 TwocheckoutFacade "order()" 方法获取 Order 对象。

$order = $tco->order();

Order 对象有一个名为 "place" 的方法，该方法会生成对 Api Core 的调用并返回一个响应

$response = $order->place( $dynamicOrderParams );

要验证响应，您首先需要检查响应中的 "refno" 键，然后对该 "refno" 执行验证 API 调用。例如

$orderData = $tco->order()->getOrder( array( 'RefNo' => $response['refNo'] ) );

然后验证 "$orderData['Status']"。对于成功放置的付款，此值是 "AUTHRECEIVED" 或 "COMPLETE"。

####2. 目录产品

$orderCatalogProductParams = array(
    'Country'           => 'br',
    'Currency'          => 'brl',
    'CustomerIP'        => '91.220.121.21',
    'ExternalReference' => 'CustOrderCatProd100',
    'Language'          => 'en',
    'BillingDetails'    =>
        array(
            'Address1'    => 'Test Address',
            'City'        => 'LA',
            'CountryCode' => 'BR',
            'Email'       => 'customer@2Checkout.com',
            'FirstName'   => 'Customer',
            'FiscalCode'  => '056.027.963-98',
            'LastName'    => '2Checkout',
            'Phone'       => '556133127400',
            'State'       => 'DF',
            'Zip'         => '70403-900',
        ),
    'Items'             =>
        array(
            0 =>
                array(
                    'Code'     => 'E377076E6A_COPY1', //Get the code from CPANEL at Setup->Products->Code 
                    column
                    'Quantity' => '1',
                ),
        ),
    'PaymentDetails'    =>
        array(
            'Type'          => 'TEST',
            'Currency'      => 'USD',
            'CustomerIP'    => '91.220.121.21',
            'PaymentMethod' =>
                array(
                    'CCID'               => '123',
                    'CardNumber'         => '4111111111111111',
                    'CardNumberTime'     => '12',
                    'CardType'           => 'VISA',
                    'ExpirationMonth'    => '12',
                    'ExpirationYear'     => '2023',
                    'HolderName'         => 'John Doe',
                    'HolderNameTime'     => '12',
                    'RecurringEnabled'   => true,
                    'Vendor3DSReturnURL' => 'www.test.com',
                    'Vendor3DSCancelURL' => 'www.test.com',
                ),
        ),
);

其余流程与使用动态产品放置订单的流程相同。

订阅助手

为了使付款可重复（生成订阅），需要将 "RecurringOptions" 字段设置为 "item"（产品）数组结构中。

此选项如何配置的示例

'RecurringOptions' =>
    array(
        'CycleLength'    => 1,
        'CycleUnit'      => 'MONTH',
        'CycleAmount'    => 3,
        'ContractLength' => 3,
        'ContractUnit'   => 'Year',
    ),

具有重复选项的项目的示例

'Items' =>
        array(
            0 =>
                array(
                    'Name'         => 'Dynamic product',
                    'Description'  => 'Product Description test',
                    'Quantity'     => 3, //units
                    'IsDynamic'    => true,
                    'Tangible'     => false,
                    'PurchaseType' => 'PRODUCT',
                    'Price'        =>
                        array(
                            'Amount' => 6, //amount in currency units
                            'Type'   => 'CUSTOM',
                        ),
                    //Dynamic product subscription.
                    'RecurringOptions' =>
                        array(
                            'CycleLength'    => 1,          //The length of the recurring billing cycle.
                            'CycleUnit'      => 'MONTH',    //Unit of measuring billing cycles (years, months).
                            'CycleAmount'    => 3,          //The amount to be billed on each renewal.
                            'ContractLength' => 3,          //The contact length for which the recurring option will apply.
                            'ContractUnit'   => 'Year',     //Unit of measuring contact length (years, months).
                        )
                )
        )

使用订单号检索付款订单的订阅

在以下示例中，我们将获取一个包含一个项目上所有订阅的数组

/**
 * This will return the following array data:
 * return an array having this structure:
 * array(
 *   'item_code' => array(
 *        0 => 'subscription1_code', 
 *        1=> 'Subscription2_code'
 *    )
 * )
**/
 
$productsRefWithSubscriptionRefArray = $tco->subscription()->getSubscriptionsByOrderRefNo( $orderData['RefNo'] );

我们可以使用检索到的数组中的索引来选择订阅引用，然后像以下示例那样检索订阅详细信息

$subscriptionSearch['SubscriptionReference'] = reset($productsRefWithSubscriptionRefArray)[0];
$subscriptionData = $tco->subscription()->searchSubscriptions($subscriptionSearch);

有关可以搜索订阅的更多参数，请参阅 API 文档此处，并检查 Subscription 类 Subscription

购买链接签名生成

要生成购买链接签名，请创建具有以下结构的数组（详情此处）

$buyLinkParameters = ‌array (
                       'address' => 'Street 1',
                       'city' => 'Cleveland',
                       'country' => 'US',
                       'name' => 'John Doe',
                       'phone' => '0018143519403',
                       'zip' => '20034',
                       'email' => 'testcustomer@2Checkout.com',
                       'company-name' => 'Verifone',
                       'state' => 'Ohio',
                       'ship-name' => 'John Doe',
                       'ship-address' => 'Street 1',
                       'ship-city' => 'Cleveland',
                       'ship-country' => 'US',
                       'ship-email' => 'testcustomer@2Checkout.com',
                       'ship-state' => 'Ohio',
                       'prod' => 'Colored Pencil',
                       'price' => 2,
                       'qty' => 1,
                       'type' => 'PRODUCT',
                       'tangible' => 0, // int 0 or 1
                       'src' => 'phpLibrary',
                       'return-url' => 'http://tcolib.local/Examples/Controllers/BuyLink/paymentCallback.php',
                       'return-type' => 'redirect',
                       'expiration' => 1617117946, // this is a dynamic unixtimestamp value
                       'order-ext-ref' => 'CustOrd101',
                       'item-ext-ref' => '20210330102546',
                       'customer-ext-ref' => 'testcustomer@2Checkout.com',
                       'currency' => 'usd',
                       'language' => 'en',
                       'test' => 1, //int (0 or 1)
                       'merchant' => '', //one needs a valid merchant id
                       'dynamic' => 1, //always int (0 or 1)
                       'recurrence' => '1:MONTH',
                       'duration' => '12:MONTH',
                       'renewal-price' => 2,
                     );

$buyLinkSignature = $tco->getBuyLinkSignature($buyLinkParameters);
$buyLinkParameters['signature'] = $buyLinkSignature;
$redirectTo = 'https://secure.2checkout.com/checkout/buy/?' . ( http_build_query( $buyLinkParameters ) );
//Now one can just redirect to the generated url.

##退款可以使用库发起全额退款。有关 2Checkout 退款的详细信息此处

$orderData = $tco->order()->getOrder( array( 'RefNo' => $this->lastRefNo ) );
//validate if requested order is valid

// Constructing FULL Refund Details
$refundData = array(
    'RefNo'        => $orderData['RefNo'], //Required
    'refundParams' => array(
        "amount"  => $orderData["GrossPrice"], //Required
        "comment" => 'REFUND Example',
        "reason"  => 'Other' //Required, default reason is "Other"
    )
);

$response = $tco->order()->issueRefund( $refundData );

处理 IPNs（即时支付通知）

IPNs 是 2Checkout 的 webhook，可以用于异步更新支付状态。即时支付通知（IPN）作为一个消息服务，为您的 2Checkout 账户生成自动订单/交易通知。使用通知通过将其与 2Checkout 账户事件同步，将订单数据处理到您自己的管理系统。

更多信息在此

####1. 验证 Ipn Hash

$params = $_POST;
    if ( ! isset( $params['REFNOEXT'] ) && ( ! isset( $params['REFNO'] ) && empty( $params['REFNO'] ) ) ) {
        throw new TcoException( 'Cannot identify order in Ipn request.' );
    }
$validIpn = $tco->validateIpnResponse($params);

####2. 生成 Ipn 响应

$responseToken = $tco->generateIpnResponse($params);
echo $responseToken;

异常

如果返回错误响应，库将抛出 TcoException。以下是一些最常见和遇到的异常

#####当遇到 curl 异常时

'Exception ApiCore response: ' + MESSAGE #####当 BuyLink 签名生成器未返回签名时。
'Api response is missing Signature parameter: ' + MESSAGE #####上述原因 + 一些关于配置或 JwtSignature 生成的相关原因
'Exception generating buy link signature: ' + MESSAGE #####当通过订单参考号检索订阅时
'Exception getting subscriptions by order RefNo.' #####当有一个或多个订阅搜索参数时
'Exception! Some subscription search parameters are not accepted: ' + MESSAGE #####当订单搜索的一些搜索参数不被接受时
Exception! Some order search parameters are not accepted: ' + MESSAGE #####如果退款失败，将引发此异常
'Error when placing refund request: ' + MESSAGE #####Buy Link 签名生成时缺少 Secret word 值
'Buy link Secret Word is not set in Tco Config! First set it and then use it.' #####当 TcoConfig 收到不被接受的参数或缺少 sellerId && secretKey 值时
'Some configuration keys are not accepted or not set!' #####在 facade 生成 buy link 签名时发生错误
'Exception getting buy link signature! Details: ' + MESSAGE #####当验证 IPN 请求失败时
'Cannot validate Ipn Request. Details:' + MESSAGE #####当生成 IPN 响应失败时
'Cannot generate Ipn Response. Details:'

2checkoutv2 / 2checkout-php-sdk

维护者

详情