README

适用于 Omnipay PHP 支付处理库的 Allsecure 交换驱动程序

Omnipay 是一个不依赖于框架、支持多网关的 PHP 5.3+ 支付处理库。本包实现了 Omnipay 的 AllSecure 支持。

Allsecure 于 2005 年成立，主要致力于帮助技术供应商及其客户简化他们的支付接受和运营。

安装

Omnipay 通过 Composer 安装。要安装，只需将其添加到您的 composer.json 文件中

{
    "require": {
        "allsecure-pay/exchange-omnipay": "~2.0"
    }
}

然后运行 composer 以更新您的依赖项

$ curl -s http://getcomposer.org/installer | php
$ php composer.phar update

基本用法

有关一般用法说明，请参阅主要的 Omnipay 存储库。

初始化网关

// Create a gateway
$gateway = Omnipay::create('AllsecureExchange');

// Initialise the gateway
$gateway->initialize(array(
    'apiKey' => 'your-api-key',
    'secretKey' => 'your-secret-key',
    'username' => 'your-username',
    'password' => 'your-password',
    'testMode'  => TRUE, // or FALSE when you are ready for live transactions
    'defaultMerchantTransactionIdPrefix'  => 'omnipay-', // prefix of the merchantTransactionId (optional)
));

注意！ 不同的支付渠道将有不同的 API 密钥

购买交易

借记 在 Allsecure Exchange 文档中

try {
    // You need to define your own $formData array
    $card = new CreditCard($formData);
    
    $request = $gateway->purchase([
        'amount' => '10.00', // this represents €10.00
        'currency' => 'EUR',
        'card' => $card,
    ]);
    
    $response = $transaction->send();

    if ($response->isSuccessful()) {

        // Do stuff here
        // Use $response->getTransactionReference() to get transaction uuid

    } else {

        // Handle errors

    }

} catch (\Guzzle\Http\Exception\ClientErrorResponseException $e) {

    // Handle Exception Errors (use $e->getResponse()->getBody() to get JSON data)

} catch (\Exception $e) {

    // Handle Exception Errors (use $e->getMessage() to get data)

}

如果您使用 Allsecure Exchange 的 payment.js 接收令牌，您还可以在有效负载中传递 transactionToken

有关有效负载的更多信息，请参阅： Allsecure Exchange 文档

有关卡数据的更多信息，请参阅： Omnipay 信用卡文档

授权交易

预先授权 在 Allsecure Exchange 文档中

预先授权在客户的支付工具上保留支付金额。

根据您的支付方式，您有最多 7 天的时间在授权过期之前完成交易。

try {
    // You need to define your own $formData array
    $card = new CreditCard($formData);
    
    $request = $gateway->authorize([
        'amount' => '10.00', // this represents €10.00
        'currency' => 'EUR',
        'card' => $card,
    ]);
    
    $response = $transaction->send();

    if ($response->isSuccessful()) {

        // Do stuff here
        // Use $response->getTransactionReference() to get transaction uuid

    } else {

        // Handle errors

    }

} catch (\Guzzle\Http\Exception\ClientErrorResponseException $e) {

    // Handle Exception Errors (use $e->getResponse()->getBody() to get JSON data)

} catch (\Exception $e) {

    // Handle Exception Errors (use $e->getMessage() to get data)

}

如果您使用 Allsecure Exchange 的 payment.js 接收令牌，您还可以在有效负载中传递 transactionToken

有关有效负载的更多信息，请参阅： Allsecure Exchange 文档

有关卡数据的更多信息，请参阅： Omnipay 信用卡文档

完成交易

完成交易可以完成之前通过预先授权方法授权的交易。

根据您的支付方式，您甚至可以仅捕获授权金额的部分金额。

try {
    // You need to define your own $formData array
    $card = new CreditCard($formData);
    
    $request = $gateway->capture([
        'amount' => '10.00', // this represents €10.00
        'currency' => 'EUR',
        'card' => $card,
        'referenceUuid' => 'bcdef23456bcdef23456', // UUID / transaction reference of a preauthorize
    ]);
    
    $response = $transaction->send();

    if ($response->isSuccessful()) {

        // Do stuff here
        // Use $response->getTransactionReference() to get transaction uuid

    } else {

        // Handle errors

    }

} catch (\Guzzle\Http\Exception\ClientErrorResponseException $e) {

    // Handle Exception Errors (use $e->getResponse()->getBody() to get JSON data)

} catch (\Exception $e) {

    // Handle Exception Errors (use $e->getMessage() to get data)

}

有关有效负载的更多信息，请参阅： Allsecure Exchange 文档

有关卡数据的更多信息，请参阅： Omnipay 信用卡文档

购买交易

借记 在 Allsecure Exchange 文档中

try {
    // You need to define your own $formData array
    $card = new CreditCard($formData);
    
    $request = $gateway->purchase([
        'amount' => '10.00', // this represents €10.00
        'currency' => 'EUR',
        'card' => $card,
        'returnUrl' => 'https://www.example.com/return', // optional
    ]);
    
    $response = $transaction->send();

    if ($response->isSuccessful()) {

        // Do stuff here
        // Use $response->getTransactionReference() to get transaction uuid

    } else {

        // Handle errors

    }

} catch (\Guzzle\Http\Exception\ClientErrorResponseException $e) {

    // Handle Exception Errors (use $e->getResponse()->getBody() to get JSON data)

} catch (\Exception $e) {

    // Handle Exception Errors (use $e->getMessage() to get data)

}

有关有效负载的更多信息，请参阅： Allsecure Exchange 文档

有关卡数据的更多信息，请参阅： Omnipay 信用卡文档

授权交易

预先授权 在 Allsecure Exchange 文档中

预先授权在客户的支付工具上保留支付金额。

根据您的支付方式，您有最多 7 天的时间在授权过期之前完成交易。

try {
    // You need to define your own $formData array
    $card = new CreditCard($formData);
    
    $request = $gateway->authorize([
        'amount' => '10.00', // this represents €10.00
        'currency' => 'EUR',
        'card' => $card,
        'returnUrl' => 'https://www.example.com/return', // optional
    ]);
    
    $response = $transaction->send();

    if ($response->isSuccessful()) {

        // Do stuff here
        // Use $response->getTransactionReference() to get transaction uuid

    } else {

        // Handle errors

    }

} catch (\Guzzle\Http\Exception\ClientErrorResponseException $e) {

    // Handle Exception Errors (use $e->getResponse()->getBody() to get JSON data)

} catch (\Exception $e) {

    // Handle Exception Errors (use $e->getMessage() to get data)

}

有关有效负载的更多信息，请参阅： Allsecure Exchange 文档

有关卡数据的更多信息，请参阅： Omnipay 信用卡文档

完成交易

完成交易可以完成之前通过预先授权方法授权的交易。

根据您的支付方式，您甚至可以仅捕获授权金额的部分金额。

try {

    $request = $gateway->capture([
        'amount' => '10.00', // this represents €10.00
        'currency' => 'EUR',
        'referenceUuid' => 'bcdef23456bcdef23456', // UUID / transaction reference of a preauthorize
    ]);
    
    $response = $transaction->send();

    if ($response->isSuccessful()) {

        // Do stuff here
        // Use $response->getTransactionReference() to get transaction uuid

    } else {

        // Handle errors

    }

} catch (\Guzzle\Http\Exception\ClientErrorResponseException $e) {

    // Handle Exception Errors (use $e->getResponse()->getBody() to get JSON data)

} catch (\Exception $e) {

    // Handle Exception Errors (use $e->getMessage() to get data)

}

有关有效负载的更多信息，请参阅： Allsecure Exchange 文档

取消交易

取消可以取消先前使用预先授权方法进行的授权。

try {

    $request = $gateway->void([
        'referenceUuid' => 'bcdef23456bcdef23456', // UUID / transaction reference of a preauthorize
    ]);
    
    $response = $transaction->send();

    if ($response->isSuccessful()) {

        // Do stuff here
        // Use $response->getTransactionReference() to get transaction uuid

    } else {

        // Handle errors

    }

} catch (\Guzzle\Http\Exception\ClientErrorResponseException $e) {

    // Handle Exception Errors (use $e->getResponse()->getBody() to get JSON data)

} catch (\Exception $e) {

    // Handle Exception Errors (use $e->getMessage() to get data)

}

有关有效负载的更多信息，请参阅： Allsecure Exchange 文档

创建卡交易

注册 在 Allsecure Exchange 文档中

将客户的支付工具注册为未来的收费（借记或预先授权）

try {

    // You need to define your own $formData array
    $card = new CreditCard($formData);

    $request = $gateway->createCard([
        'card' => $card,
    ]);
    
    $response = $transaction->send();

    if ($response->isSuccessful()) {

        // Do stuff here
        // Use $response->getTransactionReference() to get transaction uuid

    } else {

        // Handle errors

    }

} catch (\Guzzle\Http\Exception\ClientErrorResponseException $e) {

    // Handle Exception Errors (use $e->getResponse()->getBody() to get JSON data)

} catch (\Exception $e) {

    // Handle Exception Errors (use $e->getMessage() to get data)

}

有关有效负载的更多信息，请参阅： Allsecure Exchange 文档

有关卡数据的更多信息，请参阅： Omnipay 信用卡文档

删除卡交易

注销 在 Allsecure Exchange 文档中

注销使用注册删除先前注册的支付工具。

try {

    // You need to define your own $formData array
    $card = new CreditCard($formData);

    $request = $gateway->deleteCard([
        'referenceUuid' => 'ccf0ddd790db9d7ef41b',
    ]);
    
    $response = $transaction->send();

    if ($response->isSuccessful()) {

        // Do stuff here
        // Use $response->getTransactionReference() to get transaction uuid

    } else {

        // Handle errors

    }

} catch (\Guzzle\Http\Exception\ClientErrorResponseException $e) {

    // Handle Exception Errors (use $e->getResponse()->getBody() to get JSON data)

} catch (\Exception $e) {

    // Handle Exception Errors (use $e->getMessage() to get data)

}

有关有效负载的更多信息，请参阅： Allsecure Exchange 文档

有关卡数据的更多信息，请参阅： Omnipay 信用卡文档

退款交易

退款可以撤销之前通过借记或捕获执行的支付。

根据您的支付方式，您甚至可以部分退款原始交易金额。

try {

    $request = $gateway->refund([
        'amount'                => '1.25',
        'currency'              => 'EUR',
        'referenceUuid'         => '48bbd15cdf9e5b81985d',
    ]);
    
    $response = $transaction->send();

    if ($response->isSuccessful()) {

        // Do stuff here
        // Use $response->getTransactionReference() to get transaction uuid

    } else {

        // Handle errors

    }

} catch (\Guzzle\Http\Exception\ClientErrorResponseException $e) {

    // Handle Exception Errors (use $e->getResponse()->getBody() to get JSON data)

} catch (\Exception $e) {

    // Handle Exception Errors (use $e->getMessage() to get data)

}

有关有效负载的更多信息，请参阅： Allsecure Exchange 文档

有关卡数据的更多信息，请参阅： Omnipay 信用卡文档

付款交易

即将推出

增量授权

即将推出

支付响应

成功响应

对于成功的响应，通常会生成一个参考号，可以在以后捕获或退款交易。以下方法始终可用

$response = $gateway->purchase([
    'amount' => '10.00', 
    'currency' => 'EUR', 
    'card' => $card
])->send();

$response->isSuccessful(); // is the response successful?
$response->isRedirect(); // is the response a redirect?
$response->getTransactionReference(); // a transaction uuid generated by the payment gateway
$response->getMessage(); // a message generated by the payment gateway

如果您要实现退款和取消，您需要始终保存交易参考号，因为它通常用作referenceUuid。

重定向响应

处理支付后，购物车应检查响应是否需要重定向，如果是，则相应地重定向。

$response = $gateway->purchase([
    'amount' => '10.00', 
    'currency' => 'EUR', 
    'card' => $card
])->send();

if ($response->isSuccessful()) {
    // payment is complete
} elseif ($response->isRedirect()) {
    $response->redirect(); // this will automatically forward the customer
} else {
    // not successful
}

客户不会自动跳转，因为通常购物车或开发人员会想自定义重定向方法（或者如果支付处理发生在AJAX调用中，他们希望返回JS给浏览器）。

要显示自己的重定向页面，只需在响应上调用getRedirectUrl()，然后相应地显示它。

$url = $response->getRedirectUrl();

错误响应

您可以通过在响应对象上调用isSuccessful()来测试是否为成功响应。如果与网关通信出现错误，或者您的请求明显无效，将抛出异常。通常，如果网关没有抛出异常，但返回不成功的响应，则这是您应该显示给客户的消息。如果抛出异常，则可能是您的代码中的错误（缺少必填字段），或者与网关的通信错误。

最简单的方法是将整个请求包裹在try-catch块中。

try {

    $request = $gateway->refund([
        'amount'                => '1.25',
        'currency'              => 'EUR',
        'referenceUuid'         => '48bbd15cdf9e5b81985d',
    ]);
    
    $response = $transaction->send();

    if ($response->isSuccessful()) {

        // Do stuff here like marking order as complete

    } else {

        // Handle errors

    }

} catch (\Guzzle\Http\Exception\ClientErrorResponseException $e) {

    // Handle Exception Errors (use $e->getResponse()->getBody() to get JSON data)

} catch (\Exception $e) {

    // Handle Exception Errors (use $e->getMessage() to get data)

}

高级用法

使用Customer而不是CreditCard

即将推出

计划

即将推出

接受通知

即将推出

支持

如果您在使用Omnipay时遇到一般问题，我们建议在Stack Overflow上发帖。请确保添加omnipay标签，以便它容易被找到。

如果您想了解发布公告，讨论项目的想法或提出更详细的问题，还有一个您可以订阅的邮件列表。

如果您认为您发现了错误，请使用GitHub问题跟踪器报告它，或者最好是分支库并提交拉取请求。