upgplc/php-clientlibrary

此包的最新版本（1.0.1）没有可用的许可证信息。

UPG客户端库

维护者

详细信息

github.com/UPGcarts/clientlibrary

源代码

问题

安装: 218

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 4

分支: 1

开放问题: 0

1.0.1 2016-10-14 08:18 UTC

Requires

Requires (Dev)

Unknown License 774475fab6e9346e96bc4603058a03d06745498b

libraryUpg

This package is not auto-updated.

Last update: 2024-09-14 19:19:56 UTC

README

Build Status Codacy Badge

UPG API的PHP客户端库。基于此处找到的API文档：https://documentation.upgplc.com/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'] 字符串 默认区域设置（请参阅支持的语言）
  • ['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通知被接受为HTTP 200响应之前，不会发送其他MNS。

使用PayCoBridge.js

请注意，此插件不提供任何用于paybridge的javascript库。使用paybridge的集成应实现javascript库。然而，此库可用于在服务器端实现任何paybridge集成，使用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. 单击OK按钮