README

安全交易网络服务API抽象。

文档

1. 实例化Strading
2. 加载请求模板
3. 填充模板
4. 发送请求
5. 解释响应

有关不同类型的请求和所需属性的信息，请参阅安全交易网络服务API文档。

实例化Strading

Service 用于使用现有模板构建 Request 并使用您的API凭据预填充它们。

/**
 * @param string $site_reference The Merchant's Site Reference.
 * @param string $username
 * @param string $password
 * @param string $interface_url
 */
$service = new \Gajus\Strading\Service('test_github53934', 'api@anuary.com', '93gbjdMR');

加载请求模板

用于处理卡和PayPal交易的请求模板包含在库中

• paypal/order
• paypal/auth
• card/refund
• card/auth
• transactionquery

要创建新的模板，请复制相应安全交易文档中的完整请求XML。

/**
 * @param string $name Request template name, e.g. "card/order".
 * @return Gajus\Strading\Request
 */
$auth = $service->request('card/auth');

上述示例已使用 "card/auth" 模板初始化了 Request。

填充模板

模板从数组中填充，其中每个数组键都对应一个现有节点。

/**
 * Populate XML template using data from an array.
 * 
 * @param array $data ['node name' => 'text node value', 'another node[attribute]' => 'attribute value']
 * @param string $namespace XML namespace under which the node resides, e.g. /requestblock/request
 * @return null
 */
$auth->populate([
    'amount' => 100,
    'amount[currencycode]' => 'GBP',
    'email' => 'foo@bar.baz',
    'name' => [
        'first' => 'Foo',
        'last' => 'Bar'
    ],
    'payment' => [
        'pan' => '4111110000000211',
        'securitycode' => '123',
        'expirydate' => '10/2031'
    ],
    'payment[type]' => 'VISA'
],'/requestblock/request/billing');

上述示例使用 "/requestblock/request/billing" 命名空间来引用特定的XML节点。这样做可以减少数组嵌套的数量。

要预览请求，您可以检索 SimpleXMLElement

/**
 * Request XML stripped of empty tags without attributes.
 *
 * @return string
 */
$auth->getXML();

上述将产生

<?xml version="1.0"?>
<requestblock version="3.67">
    <alias>api@anuary.com</alias>
    <request type="AUTH">
        <billing>
            <amount currencycode="GBP">100</amount>
            <email>foo@bar.baz</email>
            <name>
                <last>Bar</last>
                <first>Foo</first>
            </name>
            <payment type="VISA">
                <expirydate>10/2031</expirydate>
                <pan>4111110000000211</pan>
                <securitycode>123</securitycode>
            </payment>
        </billing>
        <operation>
            <sitereference>test_github53934</sitereference>
            <accounttypedescription>ECOM</accounttypedescription>
        </operation>
    </request>
</requestblock>

未填充并且没有默认值在模板中的XML节点，将从请求XML中删除。

您可以在多个迭代中填充请求。

$auth->populate([
    'merchant' => [
        'orderreference' => 'gajus-0000001'
    ],
    'customer' => [
        'name' => [
                'first' => 'Foo',
                'last' => 'Bar'
            ],
        'email' => 'foo@bar.baz'
    ]
], '/requestblock/request');

上述将产生

<?xml version="1.0"?>
<requestblock version="3.67">
    <alias>api@anuary.com</alias>
    <request type="AUTH">
        <merchant>
            <orderreference>gajus-0000001</orderreference>
        </merchant>
        <customer>
            <email>foo@bar.baz</email>
            <name>
                <last>Bar</last>
                <first>Foo</first>
            </name>
        </customer>
        <billing>
            <amount currencycode="GBP">100</amount>
            <email>foo@bar.baz</email>
            <name>
                <last>Bar</last>
                <first>Foo</first>
            </name>
            <payment type="VISA">
            <expirydate>10/2031</expirydate>
            <pan>4111110000000211</pan>
            <securitycode>123</securitycode>
            </payment>
        </billing>
        <operation>
            <sitereference>test_github53934</sitereference>
            <accounttypedescription>ECOM</accounttypedescription>
        </operation>
    </request>
</requestblock>

用于转储XML的方法仅用于调试。您在发送请求或处理响应时无需处理XML。

更改模板目录

您可以通过调用 setTemplateDirectory() 方法来更改请求模板的位置。

$service->setTemplateDirectory('/my/templates/live/here');

$service->getTemplateDirectory(); // Returns: /my/templates/live/here

发送请求

发送请求并捕获 Response

/**
 * Issue the request.
 *
 * @return Gajus\Strading\Response
 */
$response = $auth->request();

如果HTTP响应不是 200，则将抛出 Gajus\Strading\Exception\RuntimeException。这会在您提供无效的认证凭据或您的凭据未授予您访问API端点的权限时发生。

解释响应

Response 类抽象了响应XML。

/**
 * Transaction abstracts access to the most generic information about the response:
 *
 * - request_reference
 * - transaction_type
 * - transaction_reference
 * - timestamp
 * - parent_transaction_reference
 * - authcode
 * - amount
 * - paypal_token
 * 
 * Presence of this data will depend on the type of the response you receive, e.g.
 * only PayPal order request will include "paypal_token" parameter.
 * 
 * @return array
 */
public function getTransaction ();

/**
 * This information is available when response type is "ERROR".
 *
 * @return null|Gajus\Strading\Error
 */
public function getError ();

/**
 * This information is available in response to the "paypal/order" request.
 * 
 * @return null|string URL to redirect the client to.
 */
public function getRedirectUrl () {
    return $this->redirect_url;
}

/**
 * @return string Response type.
 */
public function getType () {
    return $this->type;
}

/**
 * @return string Raw XML response.
 */
public function getXML () {
    return $this->xml->asXML();
}

错误

如果 Response 类型为 "ERROR"，则 getError 方法将返回 Gajus\Strading\Error 的实例。

/**
 * @return string
 */
public function getCode () {
    return $this->code;
}

/**
 * @return string
 */
public function getMessage () {
    return $this->message;
}

/**
 * This tag contains one or more child elements. If the error code is "30000" (Field Error)
 * then this field will contain the field (or fields) which caused the error.
 * 
 * @todo https://github.com/gajus/strading/issues/1
 * @return string
 */
public function getData () {
    return $this->data;
}