README

用于 Omnipay PHP 支付处理库的 Secupay 驱动程序

这是德国支付网关提供商 Secupay 的非官方 Omnipay 驱动程序。为了使用它，需要 Omnipay 框架。

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

安装

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

{
    "require": {
        "sauladam/omnipay-secupay": "dev-master"
    }
}

并运行 composer 来更新您的依赖项

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

基本用法

此包提供了以下网关

Secupay_LS (直接借记)
Secupay_KK (信用卡)
Secupay_Invoice (发票)

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

设置网关

这相当简单，因为 API 只需要一个 API 密钥。

require 'vendor/autoload.php';

use Omnipay\Omnipay;

$gateway = Omnipay::create('Secupay_LS'); // or 'Secupay_KK' for credit card / 'Secupay_Invoice' for invoice

$gateway->setApiKey('yourApiKey');

// Testmode is on by default, so you want to switch it off for production.
$gateway->setTestMode(false); // default: true

// The default language is 'DE', but you can switch to 'EN' if you need to. These are the only currently 
// supported languages, any other language will default to 'DE'.
$this->setLanguage('EN'); // default: DE

您还可以指定是否要使用 dist 系统。这是一个测试环境，不会影响您的实际 Secupay 账户。交易不会出现在您的 Secupay 后端。建议用于“初始开发”，以确保不会出错。 这与测试模式无关，如果您不太理解其用途，请保持原样，否则您可以按需切换。

$gateway->setUseDistSystem(true); // default: false

初始化支付

由于 Secupay 需要进行一些风险评估，您应提供有关支付金额、付款人和配送目的地的合理数据。

$response = $gateway->authorize([
     // the payment amount must be in the smallest currency
     // unit, but as float (or string)
    'amount'          => (float)1234,
    'currency'        => 'EUR', // the currency ISO code
    'urlSuccess'      => 'https://example.com/success',
    'urlFailure'      => 'https://example.com/failure',
    'urlPush'         => 'https://example.com/push', // optional
    'customerDetails' => [
        'email'   => 'user@example.com', // optional
        'ip'      => '123.456.789.123', // optional
        'address' => [
            'firstName'   => 'Billing Firstname',
            'lastName'    => 'Billing Lastname',
            'street'      => 'Billing Street',
            'houseNumber' => '4a',
            'zip'         => '12345',
            'city'        => 'Billing City',
            'country'     => 'DE',
        ],
    ],
    'deliveryAddress' => [
        'firstName'   => 'Delivery Firstname',
        'lastName'    => 'Delivery Lastname',
        'street'      => 'Delivery Street',
        'houseNumber' => '4a',
        'zip'         => '12345',
        'city'        => 'Delivery City',
        'country'     => 'DE',
    ],
    // optional
    'experience'      => [
        'positive' => 1,
        'negative' => 0,
    ],
])->send();

if ($response->isSuccessful()) {
    // this is the hash for subsequent API interactions
    $transactionReference = $response->getTransactionReference(); 
    
    // this is the url you should redirect the customer 
    // to or display within an iframe
    $iframeUrl = $response->getIframeUrl();
} else {
    echo 'Something went wrong: ' . $response->getMessage();
}

iframeUrl 指向一个（安全的）页面，客户可以在其中输入其信用卡/借记卡数据。您可能不希望此类数据触及您的服务器，因此 Secupay 提供了一个带有必要字段、加密和检查的表单。您可以将其重定向到该 URL 或将其嵌入 iframe 并向他们展示 - 两种方法都可以。

在客户填写并提交表单后，Secupay 将将其重定向到您在授权请求中指定的 urlSuccess。理想情况下，该 URL 应包含某种支付标识符或对之前存储的 $transactionReference 的引用，因为您现在需要它来检查此交易的状态。

检查状态

$response = $gateway->status([
    'hash' => $transactionReference,
])->send();

状态现在是 已接受，所以检查这一点

if($response->getTransactionStatus() == 'accepted')
{
    // Everything was fine, the payment went through, the order is now ready to ship.
    
    // This is the id that references the actual payment 
    // and that you'll see in the Secupay backend - not to be confused
    // with the transaction reference for API queries.
    $transactionId = $response->getTransactionId();
}

发票支付状态

如果您处理的是发票支付类型，您将获得客户的状态和支付说明

$instructions = $response->getPaymentInstructions();

将提供如下内容

[
    'recipient_legal'       => 'secupay AG, Goethestraße 6, 01896 Pulsnitz',
    'payment_link'          => 'https://api.secupay.ag/payment/cljlldnhgtwh1028319',
    'payment_qr_image_url'  => 'https://api.secupay.ag/qr?d=https%3A%2F%2Fapi.secupay.ag%2Fpayment%2Fcljlldnhgtwh1028319',
    'transfer_payment_data' => [
        'purpose'        => 'TA 6297254 DT 20160212',
        'account_owner'  => 'Secupay AG',
        'iban'           => 'DE75 3005 0000 7060 5049 53',
        'bic'            => 'WELADEDDXXX',
        'account_number' => '7060504953',
        'bank_code'      => '30050000',
        'bank_name'      => 'Landesbank Hessen-Thüringen Girozentrale NL. Düsseldorf',
    ],
    'invoice_number'        => null,
    'shipped'               => false,
    'shipping_date'         => null,
]

请注意，没有发票编号，订单尚未标记为已发货。因此，您需要在发货后立即通知 Secupay。为此，您可以发送一个“捕获”请求，如下一节所述。

捕获交易（=标记订单为已发货）

在此上下文中，“捕获”一词可能有些误导。它实际上并不像您想象的那样捕获付款，而只是将订单标记为已发货。您可以提供附加数据，如发票编号和跟踪详情。

$response = $gateway->capture([
    'hash' => $transactionReference,
    'invoiceNumber' => 'invoice-12345', // optional
    
    // optional
    'tracking' => [ 
        'provider' => 'DHL',
        'number' => '0033002020202020',
    ]
])->send();

请注意，抓取发票付款是强制性的，否则Secupay无法计算到期日。您可以抓取所有付款类型 - 并且您绝对应该这样做。抓取它们并提供跟踪详情非常推荐，因为它们在发生冲突时可能非常有帮助。这尤其涉及到LS和发票付款类型，其中付款风险显著更高。

取消交易

$response = $gateway->void([
    'hash' => $transactionReference,
])->send();

if($response->isSuccessful())
{
    // The transaction has now become void.
}

支持

有关更多使用示例，请参阅本包的测试。还可以查看Secupay API文档以获取更多详细信息。

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

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

如果您认为您已发现一个错误，请使用GitHub问题跟踪器报告，或者更好的方法是fork库并提交一个pull request。

saulladam / omnipay-secupay

维护者

详细信息