README

此仓库不再维护。

Omnipay: Klarna Checkout

简介

Omnipay 是一个与框架无关的、多网关支付处理库，适用于 PHP 5.6+。本包实现了 Omnipay 的 Klarna Checkout 支持。

安装

要安装，只需将其添加到您的 composer.json 文件中

$ composer require myonlinestore/omnipay-klarna-checkout

初始化

首先，创建 Omnipay 网关

$gateway = Omnipay\Omnipay::create('\MyOnlineStore\Omnipay\KlarnaCheckout\Gateway');
// or
$gateway = new MyOnlineStore\Omnipay\KlarnaCheckout\Gateway(/* $httpClient, $httpRequest */);

然后，使用正确的凭据初始化它

$gateway->initialize([
    'username' => $username, 
    'secret' => $secret,
    'api_region' => $region, // Optional, may be Gateway::API_VERSION_EUROPE (default) or Gateway::API_VERSION_NORTH_AMERICA
    'testMode' => false // Optional, default: true
]);
// or 
$gateway->setUsername($username);
$gateway->setSecret($secret);
$gateway->setApiRegion($region);

用法

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

一般流程

1. 创建 Klarna 订单
2. 更新交易（如有必要）
3. 渲染 Iframe
4. 响应重定向到 checkoutUrl 或 confirmation_url
5. 响应 结账回调
6. 响应对 push_url 的请求（表明客户已完成订单）并返回一个 确认
7. 扩展授权（如有必要）
8. 更新商家地址（如有必要）
9. 执行一个或多个 捕获、退款 或 取消 操作

授权

要创建新订单，请使用 authorize 方法

$data = [
    'amount' => 100,
    'tax_amount' => 20,
    'currency' => 'SEK',
    'locale' => 'SE',
    'purchase_country' => 'SE',
    
    'notify_url' => '', // https://developers.klarna.com/api/#checkout-api__ordermerchant_urls__validation
    'return_url' => '', // https://developers.klarna.com/api/#checkout-api__ordermerchant_urls__checkout
    'terms_url' => '', // https://developers.klarna.com/api/#checkout-api__ordermerchant_urls__terms
    'validation_url' => '', // https://developers.klarna.com/api/#checkout-api__ordermerchant_urls__validation

    'items' => [
        [
            'type' => 'physical',
            'name' => 'Shirt',
            'quantity' => 1,
            'tax_rate' => 25,
            'price' => 100,
            'unit_price' => 100,
            'total_tax_amount' => 20,
        ],
    ],
];

$response = $gateway->authorize($data)->send()->getData();

这将返回订单详情以及要在您的网站上渲染的结账 HTML 片段。

API 文档

渲染 Iframe

Klarna Checkout 在授权支付时需要渲染 iframe

$response = $gateway->fetchTransaction(['transactionReference' => 'a5bec272-d68d-4df9-9fdd-8e35e51f92ab'])
    ->send();

echo $response->getData()['checkout']['html_snippet'];

在 iframe 内提交表单后，Klarna 将将客户端重定向到提供的 confirmation_url（成功）或 checkout_url（失败）。

更新交易

在客户未授权（完成）订单之前，可以更新订单

$response = $gateway->updateTransaction([
    'transactionReference' => 'a5bec272-d68d-4df9-9fdd-8e35e51f92ab',
    'amount'           => 200,
    'tax_amount'       => 40,
    'currency'         => 'SEK',
    'locale'           => 'SE',
    'purchase_country' => 'SE',
    'items' => [/*...*/],
])->send();

响应将包含更新的订单数据。

API 文档

扩展授权

Klarna 订单授权有效至特定日期，并且可以延长（最长可达 180 天）。可以使用 fetch 请求检索更新的过期日期。

if ($gateway->extendAuthorization(['transactionReference' => 'a5bec272-d68d-4df9-9fdd-8e35e51f92ab'])->send()->isSuccessful()) {
    $expiration = new \DateTimeImmutable(
        $gateway->fetchTransaction(['transactionReference' => 'a5bec272-d68d-4df9-9fdd-8e35e51f92ab'])
            ->send()
            ->getData()['management']['expires_at']
    );
}

API 文档

捕获

$success = $gateway->capture([
    'transactionReference' => 'a5bec272-d68d-4df9-9fdd-8e35e51f92ab',
    'amount' => '995',
])->send()
->isSuccessful();

API 文档

获取

一个 Klarna 订单最初可通过结账 API 获取。在它被授权后，它将通过订单管理 API（一段时间后，将不再在结账 API 中可用）获取。此获取请求将首先检查订单是否存在于结账 API 中。如果不存在，或者状态指示订单已完成，它还将从订单管理 API 中获取订单。

$response = $gateway->fetchTransaction(['transactionReference' => 'a5bec272-d68d-4df9-9fdd-8e35e51f92ab'])
    ->send();

$success = $response->isSuccessful();
$checkoutData = $response->getData()['checkout'] ?? [];
$managementData = $response->getData()['management'] ?? [];

API 文档 | 结账 | 订单管理

确认

确认完成的订单

$success = $gateway->acknowledge(['transactionReference' => 'a5bec272-d68d-4df9-9fdd-8e35e51f92ab'])
    ->send()
    ->isSuccessful();

API 文档

退款

$success = $gateway->refund([
    'transactionReference' => 'a5bec272-d68d-4df9-9fdd-8e35e51f92ab',
    'amount' => '995',
])->send()
->isSuccessful();

API 文档

作废

您可以释放剩余的授权金额。指定特定金额是不可能的。

$success = $gateway->void(['transactionReference' => 'a5bec272-d68d-4df9-9fdd-8e35e51f92ab'])
    ->send()
    ->isSuccessful();

API 文档

更新客户地址

这可以在订单授权后更新客户地址详情时使用。此操作的成功将受 Klarna 的风险评估。两个地址都是必需的参数。

$success = $gateway->refund([
    'transactionReference' => 'a5bec272-d68d-4df9-9fdd-8e35e51f92ab',
    'shipping_address' => [
        'given_name'=> 'Klara',
        'family_name'=> 'Joyce',
        'title'=> 'Mrs',
        'street_address'=> 'Apartment 10',
        'street_address2'=> '1 Safeway',
        'postal_code'=> '12345',
        'city'=> 'Knoxville',
        'region'=> 'TN',
        'country'=> 'us',
        'email'=> 'klara.joyce@klarna.com',
        'phone'=> '1-555-555-5555'
    ],
    'billing_address' => [
        'given_name'=> 'Klara',
        'family_name'=> 'Joyce',
        'title'=> 'Mrs',
        'street_address'=> 'Apartment 10',
        'street_address2'=> '1 Safeway',
        'postal_code'=> '12345',
        'city'=> 'Knoxville',
        'region'=> 'TN',
        'country'=> 'us',
        'email'=> 'klara.joyce@klarna.com',
        'phone'=> '1-555-555-5555'
    ],
])->send()
->isSuccessful();

API 文档

更新商户参考

如果订单已被客户授权，其商户参考可以更新

$response = $gateway->updateMerchantReferences([
    'merchant_reference1' => 'foo',
    'merchant_reference2' => 'bar',
])->send();

API 文档

单位

Klarna 以如此处所述的小单位表示金额。