README

支持

您应该已经与Credit Key的实施支持工程师取得联系。您可以直接联系您的支持工程师提出任何问题或获得实施帮助。

需求

Credit Key PHP SDK需要PHP 5.6或更高版本，并加载php_curl扩展。使用Composer是可选的。

概述

Credit Key结账类似于PayPal等服务，即用户将被重定向到creditkey.com上托管的特殊结账页面以完成结账过程。

在进行商户集成之前，应先查阅Credit Key的商户实施指南。它应使您熟悉商户实施的一般要求。

在渲染您的结账页面时，您应始终调用\CreditKey\Checkout::isDisplayedInCheckout以确定是否显示Credit Key作为支付选项。

当用户在您的结账页面上选择Credit Key作为支付选项时，您需要调用\CreditKey\Checkout::beginCheckout。使用此方法，您将向Credit Key发送有关订单的信息，例如用户购物车中的项目、应收费用的总金额、用户在结账时指定的账单和发货地址等。此方法将返回一个唯一的creditkey.com URL，您应将其重定向到用户的浏览器，以便他们完成结账过程。

在Credit Key网站上成功结账后，Credit Key将用户的浏览器重定向回您提供的唯一URL以beginCheckout。此时，您应调用\CreditKey\Checkout::completeCheckout以验证支付是否成功并完成订单。在completeCheckout成功返回后，您应在您的系统中放置订单 - 然后向用户显示您自己的订单确认页面。

当订单发货时，您应该调用 \CreditKey\Orders::confirm 来通知 Credit Key 订单已发货。如果在完成结账后几天内没有调用 confirm，Credit Key 将自动在其系统中取消订单，并且不会发出付款。

如果在发货前取消订单，您可以通过调用 \CreditKey\Orders::cancel 来取消付款。要发出全额或部分退款，请使用 \CreditKey\Orders::refund。

在Credit Key结账后返回商户

您需要在您的系统中实现至少一个，可能两个端点或控制器操作，以接收从 Credit Key 结账返回的用户。这些 URL 在每次用户选择使用 Credit Key 结账的选项时提供，当调用 \CreditKey\Checkout::beginCheckout 时。它们可以是独特的用户特定 URL。

如果您提供的取消 URL 或返回 URL 包含字符串 %CKKEY%，则在重定向时，此字符串将被替换为 Credit Key 订单 ID。

返回URL

返回 URL 将是 Credit Key 在结账成功后将用户浏览器重定向到的您的系统上的 URL。当用户返回到此 URL 时，您应与 Credit Key 验证成功的付款，完成您的系统中的订单，然后显示您的订单确认页面。如果用户没有成功完成 Credit Key 结账，Credit Key 不会将用户重定向到此 URL。

我们建议为每个请求创建一个特定于会话的 URL，其中包含有关会话的标识信息，例如您系统中用作引用用户结账会话的主键。这样，您就可以轻松地将 Credit Key 订单与用户的购物车会话匹配起来。但是，如果您使用 cookie 跟踪结账会话，则通用 URL 在您的场景中可能适用。

取消URL

当结账未成功完成时，Credit Key 将将用户重定向到取消 URL - 例如，当用户取消 Credit Key 结账会话或用户无法获得贷款批准时。在许多情况下，您只需为取消 URL 提供您的结账页面 URL。但如果您想执行除了返回结账页面之外的其他操作或进行跟踪，则可以重定向到其他地方。

订单完成URL

订单完成 URL 将是 Credit Key 将用于挂起申请的您的系统上的 URL。订单可以由管理员批准（如果 return_url 不可用），以清除申请。order_complete_url 应专门为 Credit Key 设置，以便独立于借款人的客户端状态提交订单。

返回时的操作

在您设置的用于处理返回 URL 的端点中，应采取以下操作

调用 \CreditKey\Checkout::completeCheckout，通过 Credit Key 在 URL 中提供的 Credit Key 订单 ID。此方法应返回 true 来指示付款已授权，您可以继续放置订单。如果返回 false，或抛出异常，则应返回错误，不应继续放置订单。
将订单作为新的订单放置在您的系统中，作为已授权付款的订单。
调用 \CreditKey\Orders::update 向 Credit Key 提供您的本地商户订单 ID 和订单状态。

入门

使用Composer

如果你的项目使用 Composer 依赖管理器，你可以通过在命令行执行以下命令来包含 Credit Key PHP SDK：

% composer require creditkey/creditkey-php

Composer 的自动加载应该会自动加载绑定。

不使用Composer

如果你不想使用 Composer，你可以通过包含 init.php 文件来加载绑定

require_once('/path/to/creditkey-php/init.php');

模型

大多数 SDK 方法要么接受一个或多个这些模型作为参数，要么返回一个模型。所有模型在字段值只能通过构造函数设置，可以通过相应的 get 方法访问这一点上是相似的。此处文档化的所有模型都在 \CreditKey\Models 命名空间下。

地址

此对象用于表示账单地址或配送地址。

$billingAddress = new \CreditKey\Models\Address($firstName, $lastName, $companyName, $email, $address1, $address2, $city, $state, $zip, $phoneNumber);

$firstName = $billingAddress->getFirstName();
$lastName = $billingAddress->getLastName();
$companyName = $billingAddress->getCompanyName();
$email = $billingAddress->getEmail();
$address1 = $billingAddress->getAddress1();
$address2 = $billingAddress->getAddress2();
$city = $billingAddress->getCity();
$state = $billingAddress->getState();
$zip = $billingAddress->getZip();
$phoneNumber = $billingAddress->getPhoneNumber();

购物车项

此对象表示用户购物车中的产品。 $sku、$size 和 $color 都是可选的，可以是 null。$merchantProductId 是指向商家系统上产品的键。

$cartItem = new \CreditKey\Models\CartItem($merchantProductId, $name, $price, $sku, $quantity, $size, $color);

$merchantProductId = $cartItem->getMerchantProductId();
$name = $cartItem->getName();
$price = $cartItem->getPrice();
$sku = $cartItem->getSku();
$quantity = $cartItem->getQuantity();
$size = $cartItem->getSize();
$color = $cartItem->getColor();

费用

此对象表示总订单费用、应用的折扣、税费和运费。 $total 指的是小计（不含运费和税费），而 $grandTotal 指的是加上运费、税费和应用折扣后的总金额。每个字段都应该是一个浮点数值。

$shipping、$tax 和 $discountAmount 可以是 null 或 0，如果此购买不适用此值。

$charges = new \CreditKey\Models\Charges($total, $shipping, $tax, $discountAmount, $grandTotal);

$total = $charges->getTotal();
$shipping = $charges->getShipping();
$tax = $charges->getTax();
$discountAmount = $charges->getDiscountAmount();
$grandTotal = $charges->getGrandTotal();

订单

此对象用于在结账成功完成后返回关于已下订单的信息。对于消耗应用程序来说，无需实例化此对象；它由各种方法返回，但从不作为参数使用。

$orderId = $order->getOrderId();
$status = $order->getStatus();
$captureStatus = $order->getCaptureStatus();
$amount = $order->getAmount();
$refundedAmount = $order->getRefundedAmount();
$merchantOrderId = $order->getMerchantOrderId();
$status = $order->getMerchantStatus();

// Returns an array of CartItem objects
$items = $order->getItems();

// Returns an Address object
$shippingAddress = $order->getShippingAddress();

异常

Credit Key SDK 方法在遇到各种错误时会抛出以下常见异常。

ApiNotConfiguredException

当尝试在未使用 \CreditKey\Api::configure 配置 API 端点和凭据之前调用任何 SDK 方法时，会抛出 \CreditKey\Exceptions\ApiNotConfiguredException。

ApiUnauthorizedException

当 API 已配置为无效的公钥/共享密钥组合时，会抛出 \CreditKey\Exceptions\ApiUnauthorizedException。

InvalidRequestException

当消耗应用程序向 SDK 传递无效参数时，会抛出 \CreditKey\Exceptions\InvalidRequestException。

NotFoundException

当在 Orders 类的方法中找不到给定的订单 ID 时，会抛出 \CreditKey\Exceptions\NotFoundException。

OperationErrorException

当 Credit Key API 在请求过程中遇到错误时，会抛出 \CreditKey\Exceptions\OperationErrorException。

认证

configure

此方法用于向 Credit Key PHP SDK 提供要连接的 API 环境、您提供的公钥和共享密钥。公钥和共享密钥的值应由 Credit Key 支持人员提供。在调用任何其他 SDK 方法之前，必须配置 API。

第一个参数指定要连接到哪个 API 环境。有效的值是 \CreditKey\Api::PRODUCTION、\CreditKey\Api::STAGING 和 \CreditKey\Api::LOCAL_DEVELOPMENT。

\CreditKey\Api::configure(\CreditKey\Api::PRODUCTION, $publicKey, $sharedSecret);

authenticate

可以使用此方法确定是否已提供了有效的公钥和共享密钥值，并且 Credit Key API 正在运行并可访问。返回一个布尔值。

$isSuccessful = \CreditKey\Authentication::authenticate();

结账方法

isDisplayedInCheckout

当渲染结账页面时，应调用此方法以确定是否向用户提供 Credit Key 作为支付选项。$cartContents 应该是一个包含 \CreditKey\Models\CartItem 的数组，而 $customerId 应该是商家网站上用于引用此用户的唯一键。对于访客结账，$customerId 应该是 null。

$isDisplayed = \CreditKey\Checkout::isDisplayedInCheckout($cartContents, $customerId);

beginCheckout

当用户选择“信用键”作为支付方式完成结账时，应该调用此方法。此方法应使用结账页面上所有可用的客户信息调用，并将返回一个唯一的creditkey.com URL，商家网站应将用户重定向到该URL以完成结账。

参数

$cartContents - 必需 - 一个包含用户购物车中所有项目的\CreditKey\Models\CartItem对象数组。
$billingAddress - 必需 - 一个\CreditKey\Models\Address对象，描述了在结账页面上提供的客户姓名、电子邮件、电话号码和账单地址。如果您的结账页面没有收集账单地址，您必须传递此对象，至少包含$firstName、$lastName和$email字段，最好还有$phoneNumber。其他字段可以是null。
$shippingAddress - 必需 - 客户在结账页面上输入的送货地址。
$charges - 必需 - 一个\CreditKey\Models\Charges对象，描述订单金额、运费和税费金额以及任何应用的折扣。
$remoteId - 必需 - 商家应用中的一个唯一ID，用于引用此用户的结账会话。当Credit Key在成功结账后重定向回商家网站时，此ID将被引用。
$customerId - 可选 - 商家应用中的一个唯一ID，用于引用用户（如果用户已登录）。可以是null。
$returnUrl - 必需 - 商家网站上的一个唯一URL，Credit Key将在成功结账后将用户的浏览器重定向到该URL。有关更多信息，请参阅返回URL部分。
$cancelUrl - 必需 - 商家网站上的一个URL，如果Credit Key结账失败、被拒绝或由用户取消，Credit Key将重定向用户的浏览器到该URL。有关更多信息，请参阅取消URL部分。
$orderCompleteUrl - 可选 - 您的系统提供的URL，Credit Key将使用它来管理批准挂起的订单。有关更多信息，请参阅订单完成URL部分。
$mode - 必需 - 结账模式；可以是'modal'或'redirect'。

示例

$redirectUrl = \CreditKey\Checkout::beginCheckout($cartContents, $billingAddress, $shippingAddress, $charges, $remoteId, $customerId, $returnUrl, $cancelUrl, $orderCompleteUrl, $mode);

completeCheckout

成功结账后，Credit Key将重定向回商家网站，以验证支付并放置订单。此方法在订单放置时完成结账过程。如果商家未为订单调用此方法，即使客户成功完成了Credit Key的结账，也不会进行支付。$ckOrderId指的是在重定向回商家网站时返回的唯一Credit Key订单ID。返回一个布尔值，描述支付是否成功授权。有关更多信息，请参阅返回时的操作。

$isAuthorized = \CreditKey\Checkout::completeCheckout($ckOrderId);

如果此处返回false或抛出异常，您不应将订单视为有效订单。

订单管理方法

confirm

当订单发货时应该调用此方法。发送更新后的 $cartContents 和 $charges（如果自购买以来已更改），以及商家应用使用的订单 ID（$merchantOrderId）和商家系统中的订单状态（$merchantOrderStatus）。返回一个 \CreditKey\Models\Order 对象。

$order = \CreditKey\Orders::confirm($ckOrderId, $merchantOrderId, $merchantOrderStatus, $cartContents, $charges);

update

此方法可用于在 Credit Key 系统的任何时间更新 $charges、$cartContents、$shippingAddress、$merchantOrderId 或 $merchantOrderStatus。如果您不想更新与该参数关联的值，除了 $ckOrderId 之外的任何参数都可以发送 null。返回一个 \CreditKey\Models\Order 对象。

$order = \CreditKey\Orders::update($ckOrderId, $merchantOrderStatus, $merchantOrderId, $cartContents, $charges, $shippingAddress);

建议在结账后立即调用此方法，一旦在商家应用中创建相应的订单，以向 Credit Key 提供订单 ID（$merchantOrderId）。

find

使用 $ckOrderId 从 Credit Key 获取订单数据。返回一个 \CreditKey\Models\Order 对象。如果找不到订单，将抛出 \CreditKey\Exceptions\NotFoundException。

$order = \CreditKey\Orders::find($ckOrderId);

findByMerchantId

使用商家应用订单 ID 从 Credit Key 获取订单数据。如果您之前通过 API 调用未向 Credit Key 提供订单 ID（$merchantOrderId），则此方法将失败。返回一个 \CreditKey\Models\Order 对象。如果找不到订单，将抛出 \CreditKey\Exceptions\NotFoundException。

$order = \CreditKey\Orders::findByMerchantOrderId($merchantOrderId);

cancel

取消订单。此方法只能在调用 \CreditKey\Orders::confirm 之前调用。它将取消订单。此方法旨在在订单发货前取消订单时使用。返回一个 \CreditKey\Models\Order 对象。

$order = \CreditKey\Orders::cancel($ckOrderId);

refund

向客户部分或全额退款。$refundAmount 应为一个正浮点值，表示退款金额。返回一个 \CreditKey\Models\Order 对象。

$refundAmount = 29.99;
$order = \CreditKey\Orders::refund($ckOrderId, $refundAmount);

creditkey / creditkey-php

维护者

详细信息