README

UPG API的PHP客户端库。基于此处找到的API文档：[https://www.manula.com/manuals/payco/payment-api/hostedpagesdraft/en/topic/introduction](https://www.manula.com/manuals/payco/payment-api/hostedpagesdraft/en/topic/introduction)

当前问题

目前一些调用存在问题：

• CreateTransaction: API文档中将url字段重命名了
• UpdateTransaction: 目前尚未完成

使用库

配置对象

API需要正确的配置才能运行。所有需要配置的类和方法都可以传递一个已填充的Upg\Library\Config实例。

通过提供一个关联数组，在实例化时应该完全填充配置对象。

$configData = array('merchantID' => 1, 'storeID' => 1);
$config = new Upg\Library\Config($configData);

必须提供的配置字段包括：

• ['merchantPassword'] 字符串 这是用于mac计算的商户密码
• ['merchantID'] 字符串 这是UPG分配的商户ID
• ['storeID'] 字符串 这是商户的店铺ID
• ['logEnabled'] 布尔值 是否启用日志记录
• ['logLevel'] 整数 日志级别，请参阅类常量以获取可能的值
• ['logLocationMain'] 字符串 主要日志位置文件路径
• ['logLocationRequest'] 字符串 API请求的日志位置文件路径
• ['defaultRiskClass'] 字符串 默认风险类别
• ['defaultLocale'] 字符串 默认区域设置（请参阅[支持的语言](http://documentation.upgplc.com/hostedpagesdraft/en/topic/supported-languages)）
• ['sendRequestsWithSalt'] 布尔值 自动在请求中添加盐。在实际环境中应设置为true而不是false。但是，在测试中可以设置为false。默认情况下，如果没有指定，这将设置为true。
• ['baseUrl'] 字符串 请求的基本URL应包含https://sandbox.upgplc.com/2.0 或 https://www.pay-co.net/2.0

日志级别

在引用日志级别时，请确保使用Psr\Log\LogLevel静态常量。例如：\Psr\Log\LogLevel::ALERT

启动API请求

请求库分为三部分：Upg\Library\Request 包含请求类。 Upg\Library\Request\Objects 包含API文档中记录的JSON对象的类。如果请求具有需要JSON对象的属性，请传递适当的 Upg\Library\Request\Objects 类。

请求和JSON对象中的所有属性都具有getter和setter。例如，要设置请求或对象上的userType字段，您将调用 setUserType，要获取它，您将调用 getUserType。

日期字段的注意事项

请求和JSON对象中任何需要日期的字段都应传递PHP DateTime对象 - 即使该字段只需要月和年。对于只需要月和年的字段，如支付工具的有效性，请参阅DateTime::setDate。只需按照这种方式运行代码即可获取填充字段的DateTime对象

$expiryMonth = 2
$expiryYear = 2020
$date = new \DateTime();
$date->setDate($expiryYear, $expiryMonth, 1);

序列化器会将日期序列化为正确格式的字符串以供请求使用。

金额字段的注意事项

任何需要JSON金额字段的字段都应提供 Upg\Library\Request\Objects\Amount 对象。此对象有三个属性

• amount: 完整金额（小计+税）以最低货币单位表示。
• vatAmount: 如果存在，请以最低货币单位表示的增值税金额
• vatRate: 如果提供了vatAmount，请提供增值税率的详细信息，精确到小数点后两位。

所有金额值都必须以最低货币单位表示（例如分、便士等）。例如，一笔10欧元的交易，增值税率为20%，则需要填写

• amount: 1200
• vatAmount: 200
• vatRate: 20

发送请求

一旦您已填充了具有适当值的请求对象，请为适当的调用实例化一个Upg\Library\Api类。传入配置对象和要发送的请求。然后，调用sendRequest()方法将发送响应。抛出任何异常或提供成功响应。

可以抛出的异常在Upg\Library\Api\Exception中。对于任何解析的响应，您将能够访问到Upg\Library\Response\SuccessResponse或Upg\Library\Response\FailureResponse对象。如果没有抛出异常，则返回成功对象。在Upg\Library\Api\Exception\ApiError异常中返回失败对象。

响应对象有两种类型的属性：固定属性，如resultCode，在每个请求中都有，以及动态属性，如allowedPaymentMethods，不是每个请求都有。要访问固定或动态属性，只需使用以下方法

$response->getData('resultCode');
$response->getData('allowedPaymentMethods');

如果任何响应包含JSON对象或对象数组，则库将尝试将它们序列化到Upg\Library\Request\Objects类中。将在响应中序列化的属性名称如下

• allowedPaymentInstruments, paymentInstruments : Upg\Library\Request\Objects\PaymentInstrument数组
• billingAddress, shippingAddress : Upg\Library\Request\Objects\Address
• amount : Upg\Library\Request\Objects\Amount
• companyData : Upg\Library\Request\Objects\Company
• paymentInstrument : Upg\Library\Request\Objects\PaymentInstrument
• userData : Upg\Library\Request\Objects\Person

例如，getUser API调用的响应包含以下属性，将被序列化到以下对象中

• companyData字段将是一个Upg\Library\Request\Objects\Company对象
• userData字段将是一个Upg\Library\Request\Objects\Person对象
• billingAddress, shippingAddress将是一个Upg\Library\Request\Objects\Address对象

请求和响应的MAC验证/计算由库处理，如果失败则抛出异常。

所有不是ISO值的变量都定义为类中的常量，以供您在请求中使用。有关可能的固定字段值，请参阅以下常量

• locale: Upg\Library\Locale\Codes
• riskClasses: Upg\Library\Risk\RiskClass
• userType: Upg\Library\User\Type
• salutation: Upg\Library\Request\Objects\Person::SALUTATIONFEMALE Upg\Library\Request\Objects\Person::SALUTATIONMALE
• companyRegisterType: Upg\Library\Request\Objects\Company
• paymentInstrumentType: Upg\Library\Request\Objects\PaymentInstrument
• issuer: Upg\Library\Request\Objects\PaymentInstrument

库实现了所有方法的存根，除了registerMerchant，因为目前UPG仅限于授权方。

处理回调

对于reserve API调用，您可能会从API作为POST/GET请求收到一个回调。为此，客户端库实现了一个助手供您使用：Upg\Library\Callback\Handler。

该构造函数需要以下内容

• $config: 集成配置对象
• $data: 来自post\get变量的数据，应该是一个关联数组，包含以下内容
  • merchantID
  • storeID
  • orderID
  • resultCode
  • merchantReference : 可选字段
  • message : 可选字段
  • salt
  • mac
  • $processor: 一个实现Upg\Library\Callback\ProcessorInterface接口的对象实例，该方法将在验证后调用

处理器应实现两种方法：一个是处理程序使用的 sendData 方法，用于将数据传递给处理器使用；另一个是名为 run 的方法，用于处理回调处理。此处理器应返回一个字符串，其中包含用户在UPG处理交易后应重定向到的URL。

要运行处理程序，只需在对象上调用 run 方法。请注意，可能会抛出以下异常。在这种情况下，商店必须发送一个URL，但应以非200 HTTP结果码响应，以指示已出现问题。以下异常可能会抛出：

• Upg\Library\Callback\Exception\ParamNotProvided：如果未提供必需的参数
• Upg\Library\Callback\Exception\MacValidation：如果回调参数存在MAC验证问题

处理MNS通知

对于MNS通知，API提供了一个辅助类来验证MNS通知。此类是 Upg\Library\Mns\Handler。构造函数需要以下参数：

• $config: 集成配置对象
• $data：来自post/get变量的数据，应该是MNS回调的相关数组
• $processor：一个实现了Upg\Library\Mns\ProcessorInterface接口的对象实例，该方法将在验证后调用。

处理器对象应实现 sendData 以从处理程序获取数据，以及一个 run 方法，该方法在验证成功后执行回调。

处理器回调应避免处理请求，而应将其保存到数据库中，通过cron脚本来异步处理。

请注意，MNS调用必须始终返回200响应给UPG，否则不会发送其他MNS，直到接受给定的MNS通知并返回HTTP 200响应。

使用PayCoBridge.js

请注意，此插件不提供任何用于支付桥的javascript库。使用支付桥的集成应实现javascript库。但是，此库可以用于实现任何支付桥集成的服务器端功能，使用PHP作为后端。

如果您使用处理程序类将MNS保存到数据库以供以后处理，可以假设MNS完全有效，无需检查MAC。

在插件上工作

如果您想为库做出贡献，请注意，所有代码应按照 PSR2标准 编写。在PHPStorm中使用PHP-Codesniffer设置此标准非常简单。要为PHPStorm配置PHP-Codesniffer，请按照以下步骤操作：

1. 运行以下操作。

   composer global require 'squizlabs/php_codesniffer=*'

2. 在PHPStorm中打开设置对话框，导航到语言和框架 -> PHP -> Code Sniffer。
3. 在配置选项中点击...按钮，在提示中将PHPStorm指向Code Sniffer的路径。
4. 要设置代码风格，请转到编辑器 -> 代码风格 -> PHP。
5. 在设置中点击“从”设置，转到预定义样式 -> PSR1/PSR2。
6. 点击“确定”按钮。