README

A PHP封装Cheddar应用程序接口。Cheddar是一个支付网关，用于通过整洁且通用的API处理和执行交易。

目前，Cheddar和该库支持以下支付方式和服务

CardPay，可选附加ComfortPay服务 - Tatra banka, a.s.
TatraPay - Tatra banka, a.s.
ePlatby VÚB - VÚB, a.s.
VÚB eCard - VÚB, a.s.
SporoPay - Slovenská sporiteľna, a.s.
iTerminal - Poštová banka, a.s.
GP webpay - Global Payments Europe, s.r.o.
TrustCard - TrustPay, a.s.
PayPal - PayPal (Europe) S.à r.l. et Cie, S.C.A.

要查看当前版本中的新功能或更改，请查看变更日志。

要求

Cheddar需要PHP版本5.4.0或更高版本（包括PHP 7），并已安装json、hash和cURL扩展。

如果您使用Composer，这些依赖项应自动处理。如果您手动安装，请确保这些扩展可用。

设置和安装

Composer

安装库的推荐方法是使用Composer并将其作为项目composer.json文件中的依赖项添加。

composer require backbone/cheddar

然后，为了使用绑定，使用Composer的自动加载

require_once('vendor/autoload.php');

手动安装

如果您不想使用Composer，可以下载最新版本。然后，为了使用库，包含init.php文件。

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

用法

首先，您需要引入库，并通过提供您的用户句柄和共享密钥来提供认证信息。

$client = new \Cheddar\Cheddar([
	'key' => 'TEST',
	'secret' => '00000000000000000000000000000000'
]);

如果您需要访问除了生产环境之外的任何环境或运行Cheddar服务的自定义实例，您可以手动设置端点。

$client->apiEndpoint('https://...');

如果您只想使用默认Cheddar实例的沙箱版本，请运行以下命令。

$client->sandbox(true);

请注意 目前只有 VÚB eCard、iTerminal、GP webpay 和 PayPal 允许使用它们的测试环境，因此在其他提供商的情况下将使用生产 URL！在支持银行或金融机构的沙箱中使用时，切勿使用真实世界的信用卡/账户进行测试支付方式实现（它们将不起作用）。始终使用支付机构为此目的提供的虚拟测试卡/账户。

创建交易

实例化支付相当简单。

以下是一段快速示例代码，让您入门，它将调用 Cheddar 服务并检索 UUID – 交易的通用标识符，并将交易状态设置为 none（有关交易状态的更多信息，请参阅下一节）。用户的 IP 地址在发送到服务之前会自动添加到数据数组中。

$payment = $client->payment()->create(
    \Cheddar\Cheddar::SERVICE_CARDPAY, [
        'amount'           => 9.99,
        'currency'         => \Cheddar\Currencies::EUR,
        'variable_symbol'  => '1000000000',
        'payer_name'       => 'John Doe',
        'description'      => 'my first test payment',
        'payer_email'      => 'john@doe.com',
        'return_url'       => 'https://my-test-server.dev',
        'notification_url' => 'https://my-test-server.dev',
    ]
);

第一个参数是服务提供商，目前可以是以下之一

函数调用的第二个参数是配置选项的关联数组。必须使用哪些选项以及哪些选项没有任何效果取决于服务提供商。下表列出了所有可能的属性

请注意，所有受支持货币均可在 \Cheddar\Currencies 类中作为简单的常量使用，以简化代码。

调用后，您可以检查返回的 \Cheddar\Data\Payment 对象，该对象在本文档的“获取交易详情”部分有详细描述。

要获取处理支付时银行支付网关的 URL，只需调用以下代码

header('Location: ' . $payment->redirectUrl());

在支付网关完成支付过程后，您将被重定向到在上述示例中的 $client->payment()->create(...) 调用期间指定的 return_url / callback 参数中指定的 URL。该 URL 将添加两个额外的 GET 参数 - uuid，用于支付标识符和 status，用于支付交易当前状态（对于某些支付方式，这可能在时间上发生变化，并且您将通过在 notification_url 参数中指定的 URL 通知您关于变化 [有关更多信息，请参阅本文档的“异步交易通知”部分])

允许的交易状态

获取交易详情

要获取现有支付交易的详细信息，只需将支付 UUID 传递到以下方法

$payment = $client->payment()->details($uuid);

之后，您可以检查返回的 \Cheddar\Data\Payment 对象，它包含以下属性

异步交易通知

交易可能有一个 notification_url 属性（在 PayPal 和 ComfortPay 的情况下，该属性是必需的），它将在交易每次更改时接收 ping（在 PayPal 或 ComfortPay 的情况下，这也是唯一确定支付状态的方法）。

Cheddar 以 POST 请求的方式调用 notification_url 属性的值，带有 GET 属性 uuid、signature（需要验证）和 application/json 主体，其中包含如前所述的完整支付详情。

要验证签名，您需要调用以下

$client->message()->validate(
    $_GET['uuid'], $_GET['signature']
);

如果签名不正确，则抛出 \Cheddar\Exceptions\MessageIntegrityException 异常，否则函数返回 true。验证成功后，您可以信任请求的 json 编码体。

json 编码的体将如下所示

{
    "uuid": "b1fcc76a-d284-4cbc-bce9-b415dc973763",
    "service": {
        "handle": "cardpay",
        "provider": "Tatra banka, a.s.",
        "name": "CardPay"
    },
    "status": {
        "status": "completed",
        "description": "The payment has been approved by the bank or financial institution"
    },
    "variable_symbol": "1000000000",
    "constant_symbol": "0308",
    "amount": 9.99,
    "refunded_amount": 0,
    "service_fee_amount": 0,
    "currency": {
        "alpha_code": "EUR",
        "numeric_code": 978,
        "name": "Euro"
    },
    "periodicity": 0,
    "periodicity_no": 1,
    "created_at": "2018-12-01 10:34:26",
    "events": [],
    "note": "my first test payment",
    "card_no": "****************",
    "transaction_identifier": "Aq83Lys6WHdiP8TFo6pnkRvTlpC="
}

更新计划中的交易

下一个用例是能够更改下一次计划支付的日期和/或金额。调用的输出是计划支付的摘要，包括其 UUID。

$payment = $client->payment()->update($payment_uuid, [
    'charge_on' => (new \Datetime('tomorrow'))->format('Y-m-d'),
    'amount'    => 11.99
]);

然而，计划的支付状态也可能发生变化——从 none 变为 cancelled 或相反。只需确保将 charge_on 属性设置为正确的值，或者更改状态时明确设置它。

退款交易

使用Poštová banka的iTerminal服务，您可以一次性请求部分或全部执行交易的退款。在Tatra banka的CardPay服务中，您可以要求尽可能多的退款，直到所有先前退款的总和达到原始交易金额。

reason 更具有信息性，应选择以下之一：requested_by_customer（由客户请求）、fraudelent（欺诈）、duplicate（重复）或unknown（默认）。货币必须与执行原始支付时相同。

$payment = $client->payment()->refund($payment_uuid, [
    'amount' => 11.99,
    'currency' => \Cheddar\Currencies::EUR,
    'reason' => 'requested_by_customer'
]);

贡献

检查开放问题或为新功能请求或错误打开一个新问题。
对存储库进行分支并更改主分支（或从其分支）。
发送拉取请求。

待办事项

功能彻底测试
使用您自己的HTTP客户端的能力

开发

按照上述说明安装依赖项，然后运行测试套件

./vendor/bin/phpunit

或运行单个测试文件

./vendor/bin/phpunit tests/CurlTransportTest.php

backbone / cheddar

维护者

详细信息