Klarna driver for the Omnipay PHP payment processing library
Master branch:
Feature Checkout branch:
Omnipay is a framework agnostic, multi-gateway payment processing library for PHP 5.3+. This package implements Klarna support for Omnipay.
- This is a work-in-progress, unstable version. Stable version has not yet been released.
- Error handling implementation uses this heuristics:
if code of
KlarnaException
thrown is below 0 or above 1100, it is assumed, that it contains message to be displayed to customer, otherwise technical error is assumed and the exception is rethrown.
- PHP 5.4+
- Klarna API credentials
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).
The following gateways are provided by this package:
Klarna\Invoice
Klarna\Checkout
(only available in branch dev-feature/checkout)
Gateways in this package have following required options:
merchantId
sharedSecret
To get those please contact your Klarna representative.
Additionally these options could be specified:
testMode
country
language
currency
You can set up country, language and currency (for supported countries) at once using setLocale()
method.
For meaning of testMode
see general Omnipay documentation
Gateway Klarna\Invoice
supports these request-sending methods:
authorize()
capture()
checkOrderStatus()
For use and expected parameters see unit tests and example code
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:
merchantId
(may be inherited from gateway)sharedSecret
(may be inherited from gateway)country
(may be inherited from gateway)language
(may be inherited from gateway)currency
(may be inherited from gateway)card
items
These are optional parameters:
amount
transactionId
alias fororderId1
orderId2
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.
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:
gender
for DE/AT/NLbirthday
for DE/AT/NLnationalIdentificationNumber
- personal number for other countries; also may by used for company number when needed
Address parameters:
phone
mobile
firstName
lastName
postCode
city
country
company
address1
address2
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
...
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:
name
("title")identifier
("article number")quantity
price
taxPercent
("VAT")discountPercent
("discount")flags
When all required parameters are set on InvoiceAuthorizeRequest
object,
you can call its method send()
, to receive InvoiceAuthorizeResponse
object.
InvoiceAuthorizeResponse
object has following methods:
isSuccessful()
- alias forisAccepted()
isWaiting()
- alias forisPending()
getInvoiceStatus()
getReservationNumber
getMessage()
getCode()
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.
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.
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:
merchantId
(may be inherited from gateway)sharedSecret
(may be inherited from gateway)country
(may be inherited from gateway)language
(may be inherited from gateway)currency
(may be inherited from gateway)reservationNumber
These are optional parameters:
OCRNumber
flags
transactionId
alias fororderId1
orderId2
When all required parameters are set on InvoiceCaptureRequest
object,
you can call its method send()
, to receive InvoiceCaptureResponse
object.
InvoiceCaptureResponse
object has following methods:
isSuccessful()
- alias forisAccepted()
getTransactionReference
alias forgetInvoiceNumber()
getRiskStatus()
getMessage()
getCode()
For error and exception handling see Errors and Exceptions above.
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:
merchantId
(may be inherited from gateway)sharedSecret
(may be inherited from gateway)country
(may be inherited from gateway)language
(may be inherited from gateway)currency
(may be inherited from gateway)
One of these parameters is also required:
reservationNumber
invoiceNumber
orderId
or its aliastransactionId
When all required parameters are set on InvoiceCheckOrderStatusRequest
object,
you can call its method send()
, to receive InvoiceCheckOrderStatusResponse
object.
InvoiceCaptureResponse
object has following methods:
isSuccessful()
- alias forisAccepted()
isWaiting()
- alias forisPending()
isDenied()
getOrderStatus()
getMessage()
getCode()
For error and exception handling see Errors and Exceptions above.
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
.
For example code see:
- GET Prepare page
- POST Authorize page
- GET Check page
- GET Capture page
Both InvoiceGateway
and InvoiceAuthorizeRequest
have method getWidget()
, which is returning InvoiceWidget
,
with (among others) following methods:
getDefaultParameters()
getRequiredParameters()
isRenderable()
render()
renderPaymentMethodWidget()
renderLogoUrl()
renderTooltip()
renderTermsInvoiceHtml()
renderTermsConsentHtml()
renderTermsAccountHtml()
Class also contains following static methods:
assemblePaymentMethodWidgetHtml()
assembleLogoUrl()
assembleTooltipHtml()
assembleTermsInvoiceObject()
assembleTermsConsentObject()
assembleTermsAccountObject()
assembleTermsConsentText()
assembleLoadJavascript()
assembleLoadTermsJavascript()
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:
merchantId
(may be inherited from gateway orInvoiceAuthorizeRequest
)country
(may be inherited from gateway orInvoiceAuthorizeRequest
)language
(may be inherited from gateway orInvoiceAuthorizeRequest
)price
(may be inherited fromInvoiceAuthorizeRequest
-amount
or calculated amount)
Optional parameters:
charge
- "invoice-fee" - numeric string in format'0.95'
layout
- argument array key only; if not set the default may be affected bycolor
parameterwidth
- argument array key onlyheight
- argument array key onlystyle
- argument array key only; additional style setting of container<div>
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.
For general usage instructions, please see the main Omnipay repository.
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.
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.
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.
- Klarna developers documentation: https://developers.klarna.com
- Omnipay Library web page: http://omnipay.thephpleague.com
- Omnipay Library Github Project: https://github.com/thephpleague/omnipay