README

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

使用方法：克隆并使用composer要求，或要求包含的自动加载器。

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

放置订单助手

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

动态产品

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

订单对象有一个名为"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类

生成购买链接签名

要生成购买链接签名，创建以下结构的数组（详细信息在此）

$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的webhooks，可用于异步更新支付状态。即时支付通知（IPN）充当消息服务，为您的2Checkout账户生成自动订单/交易通知。使用通知将订单数据同步到您的管理系统中，以处理2Checkout账户事件。

更多详细信息在此

####1. 验证Ipn哈希

$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响应缺少Signature参数: " + MESSAGE #####上述原因 + 关于配置或JwtSignature生成的其他原因。
"生成buy link签名异常: " + MESSAGE #####当通过订单参考号检索订阅时。
"通过订单RefNo.获取订阅异常#####当有一个或多个订阅搜索参数时。
"异常！某些订阅搜索参数不被接受: " + MESSAGE #####当某些订单搜索参数不被接受时。
异常！某些订单搜索参数不被接受#####如果退款失败，则抛出此异常。
"提交退款请求时出错: " + MESSAGE #####Buy Link签名生成缺少密钥值。
"Buy link密钥词未在Tco Config中设置！首先设置它然后使用它。"#####当TcoConfig收到不被接受的参数或sellerId && secretKey值缺失时。
"某些配置键不被接受或未设置！"#####在facade中生成buy link签名时出现问题。
"获取buy link签名异常！详细信息: " + MESSAGE #####当验证IPN请求失败时。
"无法验证IPN请求。详细信息：" + MESSAGE#####当生成IPN响应失败时。
"无法生成IPN响应。详细信息："

imlolman / 2checkout-php-sdk

维护者

详细信息