README

PSIGate XML 消息传递和账户管理 API 的 PHP 实现。

警告（2017-10-23）

由于 API 网关的 URL 结构发生变化，从 2017-10-23 之前更新到最新的 dev-master 版本时可能会出现不兼容问题。为了解决这个问题（我的错误没有立即引入版本历史），引入了版本历史。如果您想使用旧版本，即不修改当前代码，请在 composer 文件中将 dev-master 更改为 0.9。为了避免潜在的将来兼容性问题，将 dev-master 更改为最相关的当前版本。

一般信息

该库是围绕 PSIGate XML API 的包装，使输入和结果数组结构反映 PSIGate 网关期望的 XML 文档结构。请参考原始 PSIGate 文档以了解要设置的参数和预期结果值。

安装

安装该库的推荐方式是通过 Composer。

{
    "require": {
        "propa/psigate": "~1"
    }
}

异常处理

如果在请求处理过程中发生错误，则会抛出异常。异常代码以相应的 PSIGate API 错误代码（RPA-0002，RIV-0019 等）初始化，异常消息以相应的错误消息，请参考 PSIGate API 文档以获取错误代码和关联消息的完整列表。

存在一些与意外响应格式、cURL 和其他情况相关的特定于 PHP API 的错误，它们的异常代码以 PAPI 和 CURL 前缀（例如 PAPI-0001，PAPI-0002，CURL-0001，CURL-0006 等）。

请注意，如果未抛出异常，并不意味着操作在一般情况下是成功的。例如，AMMessenger::chargeImmediate() 返回 Invoice 结构，即使交易被处理网关拒绝且信用卡未扣款。存在 Messenger::analyseTransactionResult() 方法，可以用来检查数据结构是否包含错误信息。

XML 消息传递（XMLMessenger）

XML 消息传递允许处理实时信用卡交易。

基本用法

<?php
$xmlm = new \PSIGate\XMLMessenger('https://realtimestaging.psigate.com/xml', 'teststore', 'psigate1234');
try {
    $result = $xmlm->order(array(
        'Subtotal' => '10.00',
        'PaymentType' => 'CC',
        'CardAction' => '0',
        'CardNumber' => '4111111111111111',
        'CardExpMonth' => '02',
        'CardExpYear' => '16',
        'CardIDNumber' => '1234',
        'Item' => array(
            array(
                'ItemID' => 'PSI-BOOK',
                'ItemDescription' => 'XML Interface Doc',
                'ItemQty' => '1',
                'ItemPrice' => '10.00',
                'Option' => array(
                    'Type' => 'Electronic',
                    'File' => 'xml.doc',
                ),
            ),
            array(
                'ItemID' => 'COUPON',
                'ItemDescription' => '10% discount',
                'ItemQty' => '1',
                'ItemPrice' => '-2.00',
            ),
        ),
    ));
    
    // analyze transaction result ...
    
} catch (\PSIGate\Exception $e) {
    // handle transaction error ...
}

账户管理（AMMessenger）

账户管理服务允许注册客户支付账户，存储客户支付信息以供将来定期或实时授权，以发票的形式跟踪客户的定期或实时交易活动。

基本用法

<?php
$amm = new \PSIGate\AMMessenger('https://accountsstaging.psigate.com/xml', '1000001', 'teststore', 'testpass');
try {
    // register a new account
    $accountResult = $amm->accountRegister(array(
        'Name' => 'John Smith Jr.',
        'Company' => 'PSiGate Inc.',
        'Address1' => '145 King St.',
        'Address2' => '2300',
        'City' => 'Toronto',
        'Province' => 'Ontario',
        'Postalcode' => 'M5H 1J8',
        'Country' => 'Canada',
        'Phone' => '1-905-123-4567',
        'Fax' => '1-905-123-4568',
        'Email' => 'support@psigate.com',
        'Comments' => 'No Comment Today',
        'CardInfo' => array(
            'CardHolder' => 'John Smith',
            'CardNumber' => '4005550000000019',
            'CardExpMonth' => '08',
            'CardExpYear' => '11',
        ),
    ));
    
    // retrieve newly assigned account id
    $accountId = $accountResult['AccountID'];
    $cardSerialNo = $accountResult['CardInfo']['SerialNo'];
    
    // register a charge
    $chargeResult = $amm->chargeRegister(array(
        'StoreID' => 'teststore',
        'AccountID' => $accountId,
        'SerialNo' => $cardSerialNo,
        'RBName' => 'Monthly Payment',
        'Interval' => 'M',
        'RBTrigger' => '12',
        'EndDate' => '2011.12.31',
        'ItemInfo' => array(
            'ProductID' => 'NEWSPAPER',
            'Description' => 'TORONTO STAR',
            'Quantity' => '1',
            'Price' => '25',
            'Tax1' => '2',
            'Tax2' => '1.25',
        ),
    ));
    
    // retrieve newly created charge id
    $chargeId = $chargeResult['RBCID'];
    
    // disable a charge
    $amm->chargeDisable($chargeId);
    
    // ...
    
} catch (\PSIGate\Exception $e) {
    // handle error ...
}

返回值

AMMessenger 方法的返回值可以分为以下几组

总结操作（accountSummary，invoiceSummary 等）。这些可以返回空结果（NULL），单个记录（一维数组）或多个记录（数组数组）。由于事先不知道指定的过滤器规则将产生多少结果，调用脚本必须能够灵活处理可能的返回结构。
详细操作（accountDetails，chargeDetails 等）。这些返回空结果（NULL），如果没有找到指定 ID 的记录，或者返回单个记录。
在 PSIGate 数据库中创建记录的操作（accountRegister，accountCardAdd，chargeRegister 等）。这些返回在过程中创建的记录，通常由调用脚本用于获取 PSIGate 生成的字段（记录 ID、交易状态等）。
更新或删除现有记录的操作（accountUpdate，templateDisable，chargeDelete，emailReportDelete 等）。这些返回与相应操作对应的 PSIGate 成功代码，因为每个动作类型的成功代码不会改变，因此此返回值对调用脚本来说并不那么有用，通常可以忽略。

已知问题（2013-11-21）

账户管理器API文档v1.1.08与实际API行为之间存在不一致。由于PHP API是一个简单的中介接口，问题的根源在于PSIGate服务器本身。

并非所有返回代码和消息都有文档记录（例如，“EMR-0099 立即电子邮件报告已成功发送。”）。
某些方法返回的成功代码与文档中假设的不同，例如，账户卡更新操作（AMA12）返回“RPA-0022 更新账户操作已完成。”，尽管文档中列出了更具体的“RPA-0025 更新卡操作已完成。”。
摘要操作不支持文档中指定的所有过滤器。
摘要操作没有要求使用过滤器，尽管文档可能将其列出。
注册操作返回生成的ID（除非明确指定），除了“CTL01 注册模板”返回空值的TemplateID，尽管后续的详细信息请求显示TemplateID已生成。
在负责模板相关的操作中，除了模板项目添加（CTL11）外，触发日期必须与触发器一起指定，而不是像文档中建议的那样使用RBTrigger。
删除、启用、禁用模板以及删除、启用和禁用模板项目操作（CTL04、CTL08、CTL09和CTL14、CTL18、CTL19分别）期望提供带有RBCID条件的模板ID，而不是像文档建议的那样使用TemplateID。
项目添加操作仅使用持有者ID（RBCID或TemplateID）不满意，因为PSIGate对条件等效元素进行验证，因此必须提供定义在持有者注册操作中的所需字段，即使持有者ID就足够了。
注册收费操作（RBC01）需要设置所需字段，无论收费是基于具有相同定义的模板创建的事实。
发票响应元素中的即时收费操作（RBC99）返回RBCID值两次。

propa / psigate

维护者

详细信息

README

一般信息

安装

异常处理

XML 消息传递（XMLMessenger）

基本用法

账户管理（AMMessenger）

基本用法

返回值

已知问题（2013-11-21）