search

Subscribo / omnipay-klarna

Klarna driver for the Omnipay payment processing library
MIT License
7 stars 3 forks source link

readme

Omnipay: Klarna

Klarna driver for the Omnipay PHP payment processing library

Master branch: Build Status Feature Checkout branch: Build Status

Omnipay is a framework agnostic, multi-gateway payment processing library for PHP 5.3+. This package implements Klarna support for Omnipay.

Important notes:

Requirements

Installation

Omnipay Klarna driver is installed via Composer. To install, add it to your composer.json file:

For beta version use:

{
    "require": {
        "subscribo/omnipay-klarna": "^0.1.4"
    }
}

For development version use:

{
    "require": {
        "subscribo/omnipay-klarna": "^0.1.*@dev"
    }
}

When you want to use feature branch Checkout, use:

{
    "require": {
        "subscribo/omnipay-klarna": "dev-feature/checkout",
        "klarna/checkout": "1.2",
        "subscribo/psr-http-message-tools": "~0.4.3"
    }
}

After updating composer.json run composer update to update your dependencies:

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

If you want to run online tests, you also need to set environment variables KLARNA_MERCHANT_ID and KLARNA_SHARED_SECRET with your Klarna API test credentials. These are also needed for examples, provided in docs/example/invoice (they are used usually around lines 12-13 of the examples, but you can modify them and provide credentials differently).

Basic Usage

The following gateways are provided by this package:

Gateways in this package have following required options:

To get those please contact your Klarna representative.

Additionally these options could be specified:

You can set up country, language and currency (for supported countries) at once using setLocale() method.

For meaning of testMode see general Omnipay documentation

Usage of gateway Klarna\Invoice

Gateway Klarna\Invoice supports these request-sending methods:

For use and expected parameters see unit tests and example code

authorize()

You may see official documentation and related links for additional information.

Method authorize() may have an array with parameters as its optional argument, or parameters could be specified via setters on returned InvoiceAuthorizeRequest object.

These are required parameters:

These are optional parameters:

If amount is not provided, it is set to -1 and items are used to calculate the amount. You may use method calculateAmount() to check this value.

Card

Customer personal and contact data could be sent via card parameter or setCard() setter method, either in form of an array or a Subscribo\Omnipay\Shared\CreditCard object extending Omnipay\Common\CreditCard

Following card parameters might be used:

Personal parameters:

Address parameters:

For DE/AT/NL you can pass house number as address2, for other countries is address2 simply attached with space to address1.

You can pass also different shipping address using shipping variants of parameters, i.e. shippingFirstName...

Items

Shopping cart items should be sent via items parameter or setItems() setter method, either in form of an array of arrays, or an array of Subscribo\Omnipay\Shared\Item objects or a Subscribo\Omnipay\Shared\ItemBag object.

Following item parameters might be used:

Sending

When all required parameters are set on InvoiceAuthorizeRequest object, you can call its method send(), to receive InvoiceAuthorizeResponse object.

InvoiceAuthorizeResponse object has following methods:

In case authorization was successful, you can use getReservationNumber() for parameter of capture() gateway call. In case authorization is waiting, you can use getReservationNumber() for parameter of later checkOrderStatus() gateway call.

Errors and exceptions

If authorization was rejected, getMessage() should contain displayable message for customer and getCode() exception code number. In case of technical error a KlarnaException should be thrown.

Important note: in the background, KlarnaException is thrown for both technical errors and for authorization rejections. However, if the code is below 0 or over 1100, it is converted to InvoiceAuthorizeResponse. See https://developers.klarna.com/en/at+php/kpm/error-codes for more details.

capture()

Method capture() may have an array with parameters as its optional argument, or parameters could be specified via setters on returned InvoiceAuthorizeRequest object.

These are required parameters:

These are optional parameters:

Sending

When all required parameters are set on InvoiceCaptureRequest object, you can call its method send(), to receive InvoiceCaptureResponse object.

InvoiceCaptureResponse object has following methods:

For error and exception handling see Errors and Exceptions above.

checkOrderStatus()

Method checkOrderStatus() may have an array with parameters as its optional argument, or parameters could be specified via setters on returned InvoiceCheckOrderStatusRequest object.

These are required parameters:

One of these parameters is also required:

Sending

When all required parameters are set on InvoiceCheckOrderStatusRequest object, you can call its method send(), to receive InvoiceCheckOrderStatusResponse object.

InvoiceCaptureResponse object has following methods:

For error and exception handling see Errors and Exceptions above.

OrderIds

You can set up two custom reference identifiers on each invoice - orderId1 and orderId2. For InvoiceAuthorizeRequest and InvoiceCaptureRequest parameter transactionId is an alias for orderId1.

You can search for unique orderId (whether orderId1 or orderId2) setting parameter orderId in InvoiceCheckOrderStatusRequest. In InvoiceCheckOrderStatusRequest is transactionId an alias for orderId.

Example code

For example code see:

InvoiceWidget

Both InvoiceGateway and InvoiceAuthorizeRequest have method getWidget(), which is returning InvoiceWidget, with (among others) following methods:

Class also contains following static methods:

Parameters for rendering methods could be set via constructor, setter, or passed as keys of argument array. Some parameters could be passed only as keys of argument array.

Default rendering method render() is an alias for renderPaymentMethodWidget() - rendering of part-payment / payment method widget

Required parameters:

Optional parameters:

For use and expected parameters of other rendering methods you may see the code, example code and unit tests as well as official documentation and related links.

General instructions

For general usage instructions, please see the main Omnipay repository.

Testing

For testing you need to install development dependencies:

    cd path/to/your/project
    cd vendor/subscribo/omnipay-klarna
    composer update

If you want to run both online and offline tests, run just phpunit.

If you want to run offline (not requiring internet connection) tests only, run phpunit tests/offline

If you want to run online tests, you also need to set environment variables KLARNA_MERCHANT_ID and KLARNA_SHARED_SECRET with your Klarna API test credentials.

Support

General

If you are having general issues with Omnipay, we suggest posting on Stack Overflow. Be sure to add the omnipay tag so it can be easily found.

If you want to keep up to date with release announcements, discuss ideas for the project, or ask more detailed questions, there is also a mailing list which you can subscribe to.

Omnipay Klarna driver specific

If you believe you have found a bug, please send us an e-mail (packages@subscribo.io) or report it using the GitHub issue tracker, or better yet, fork the library and submit a pull request.

Links