Code Samples

Documentation for the Payson Checkout .NET library hosted at GitHub.

.NET: https://github.com/PaysonAB/PaysonCheckout-.NET

PHP: https://github.com/PaysonAB/PaysonPayments-PHP
Code examples for the PHP library are included in the example folder.

Initiate API

$merchantId = '4';
$apiKey = '2acab30d-fe50-426f-90d7-8c60a7eb31d4';
$environment = true;
$paysonApi = new PaysonEmbedded\PaysonApi($merchantId, $apiKey, $environment);

Parameter	Type	Description
$merchantId	string		R
$apiKey	string		R
$environment	boolean	Default false	O

var paysonMerchantId = "4";
var paysonApiKey = "2acab30d-fe50-426f-90d7-8c60a7eb31d4";
var inTestMode = true;
var apiCaller = new ApiCaller(paysonMerchantId, paysonApiKey, inTestMode);

Parameter	Type	Description
var paysonMerchantId	string		R
var paysonApiKey	string		R
var inTestMode	bool	Default false	O

Get account information

$accountStatus = $paysonApi->Validate();

var accountStatus = apiCaller.Validate();

Create merchant

$checkoutUri = 'https://www.mystore.com/checkout.php';
$confirmationUri = 'https://www.mystore.com/confirmation.php';
$notificationUri = 'https://www.mystore.com/notification.php';
$termsUri = 'https://www.mystore.com/terms.php';
$paysonMerchant = new PaysonEmbedded\Merchant($checkoutUri, $confirmationUri, $notificationUri, $termsUri);

Parameter	Type	Description
$checkoutUri	string	URI to the checkout page	R
$confirmationUri	string	URI to the confirmation page	R
$notificationUri	string	URI to the notifictaion page	R
$termsUri	string	URI to the terms page	R
$partnerId	string	Only used by partners. Default null	O
$integrationInfo	string	Default ‘PaysonCheckout2.0\|x.x.x\|NONE’	O
$reference	string	Default null	O
$validationUri	string	URI to an optional validation page used to verify an order before it can be paid. Can for example be used to make sure all products are still in stock before payment is done. This URI must return HTTP 200 OK for the payment to succeed. Make sure the URI is publicly accessible. Default null	O

var merchant = new Merchant()
{
    CheckoutUri = new System.Uri("https://www.mystore.com/checkout"),
    NotificationUri = new System.Uri("https://www.mystore.com/notification"),
    ConfirmationUri = new System.Uri("https://www.mystore.com/confirmation"),
    TermsUri = new System.Uri("https://www.mystore.com/terms")
};

Parameter	Type	Description
CheckoutUri	System.Uri	URI to the checkout page	R
ConfirmationUri	System.Uri	URI to the confirmation page	R
NotificationUri	System.Uri	URI to the notifictaion page	R
TermsUri	System.Uri	URI to the terms page	R
PartnerId	string	Only used by partners. Default null	O
Reference	string	Default null	O
ValidationUri	System.Uri	URI to an optional validation page used to verify an order before it can be paid. Can for example be used to make sure all products are still in stock before payment is done. This URI must return HTTP 200 OK for the payment to succeed. Make sure the URI is publicly accessible. Default null	O

Create order

$currencyCode = 'SEK';
$payData = new PaysonEmbedded\PayData($currencyCode);

Parameter	Type	Description
$currencyCode	string	‘SEK’ or ‘EUR’	R

var order = new Order()
{
    Currency = Currency.SEK
};

Parameter	Type	Description
Currency	PaysonIntegrationCO2.Models.Enums.Currency	SEK or EUR	R

Create order item

$name = 'Product Name';
$unitPrice = 499.00;
$quantity = 1.00;
$taxRate = 0.25;
$reference = 'MDO0001';
$itemType = 'Physical';
$orderItem = new PaysonEmbedded\OrderItem($name, $unitPrice, $quantity, $taxRate, $reference, $itemType);

// Add order item to order
$payData->AddOrderItem($orderItem);

Parameter	Type	Description
$name	string	Product name	R
$unitPrice	float	2 decimals, make sure all tax rounding has been done before sending to Payson	R
$quantity	float		R
$taxRate	float		R
$reference	string		R
$itemType	string	‘Physical’, ‘Fee’, ‘Discount’ or ‘Service’. Default ‘Physical’	O
$discountRate	float		O
$ean	String (8-18)		O
$uri	string	URI for product page	O
$imageUri	string	URI for product image	O

var orderItem = new Item()
{
    DiscountRate = 0.0m,
    Name = "Product Name",
    Quantity = 1,
    Reference = "MDO0001",
    TaxRate = (decimal)0.25,
    Type = ItemType.Physical,
    UnitPrice = 499
};

// Add order item to order
order.Items.Add(orderItem);

Parameter	Type	Description
Name	string	Product name	R
UnitPrice	decimal	2 decimals, make sure all tax rounding has been done before sending to Payson	R
Quantity	decimal		R
TaxRate	decimal		R
Reference	string		R
Type	PaysonIntegrationCO2.Models.Enums.ItemType	Physical, Fee, Discount or Service	O
DiscountRate	decimal		O
Ean	string		O
Uri	System.Uri	URI for product page	O
ImageUri	System.Uri	URI for product image	O

Create GUI

$locale = 'sv';
$colorScheme = 'white';
$verification = 'none';
$requestPhone = false;
$countries = array('SE', 'DK', 'FI');
$phoneOptional = false;
$gui = new PaysonEmbedded\Gui($locale, $colorScheme, $verification, $requestPhone, $countries, $phoneOptional);

Parameter	Type	Description
$locale	string	‘sv’, ‘fi’, ‘da’, ‘no’ or ‘en’. Default ‘sv’	O
$colorScheme	string	‘Gray’ or ‘White’	O
$verification	string	‘none’ or ‘bankid’. Default ‘none’	O
$requestPhone	boolean		O
$countries	array	Array of selectable countries, null will display all countries. Default null	O
$phoneOptional	boolean		O

var gui = new Gui()
{
    RequestPhone = false,
    ColorScheme = ColorScheme.Gray,
    Locale = "sv",
    PhoneOptional = false
};

Parameter	Type	Description
Locale	string	“sv”, “fi”, “da”, “no” or “en”	R
ColorScheme	PaysonIntegrationCO2.Models.Enums.ColorScheme	White or Gray	O
RequestPhone	bool		O
PhoneOptional	bool		O

Create customer

$firstName = 'Tess T';
$lastName = 'Persson';
$email = 'test@payson.se';
$phone = '1111111';
$identityNumber = '4605092222';
$city = 'Stan';
$countryCode = 'SE';
$postalCode = '99999';
$street = 'Storgatan 66';
$type = 'person';
$customer = new PaysonEmbedded\Customer($firstName, $lastName, $email, $phone, $identityNumber, $city, $countryCode, $postalCode, $street, $type);

Parameter	Type	Description
$firstName	string		O
$lastName	string		O
$email	string		O
$phone	string		O
$identityNumber	string		O
$city	string		O
$countryCode	string		O
$postalCode	string		O
$street	string		O
$type	string	‘person’ or ‘business’. Default ‘person’	O

var customer = new Customer()
{
    FirstName = "Tess T",
    LastName = "Persson",
    Email = "test@payson.se",
    Phone = "1111111",
    IdentityNumber = "4605092222",
    City = "Stan",
    CountryCode = "SE",
    PostalCode = "99999",
    Street = "Storgatan 66",
    Type = CustomerType.Person
};

Parameter	Type	Description
FirstName	string		O
LastName	string		O
Email	string		O
Phone	string		O
IdentityNumber	string		O
City	string		O
CountryCode	string		O
PostalCode	string		O
Street	string		O
Type	PaysonIntegrationCO2.Models.Enums.CustomerType	Person or Business	O

Create checkout

$checkout = new PaysonEmbedded\Checkout($paysonMerchant, $payData, $gui, $customer);
$paysonCheckout = $paysonApi->CreateGetCheckout($checkout);

Parameter	Type
$paysonMerchant	PaysonEmbedded\Merchant	R
$payData	PaysonEmbedded\PayData	R
$gui	PaysonEmbedded\Gui	O
$customer	PaysonEmbedded\Customer	O
$description	string	O
$expirationTime	string	O

var checkout = new Checkout()
{
    Merchant = merchant,
    Order = order,
    Customer = customer,
    Gui = gui
};
var location = apiCaller.NewCheckout(checkout);
var paysonCheckout = apiCaller.GetCheckout(location);

Parameter	Type
Merchant	PaysonIntegrationCO2.Models.Merchant	R
Order	PaysonIntegrationCO2.Models.Order	R
Gui	PaysonIntegrationCO2.Models.Gui	R
Customer	PaysonIntegrationCO2.Models.Customer	R
ExpirationTime	System.DateTime	O

Get existing checkout

$existingCheckoutId = 'a273a0b8-402c-428f-99a0-a93f00df6bf6';

$paysonCheckout = $paysonApi->GetCheckout($existingCheckoutId);

Parameter	Type	Description
$existingCheckoutId	String, existing checkout ID, e.g ‘a273a0b8-402c-428f-99a0-a93f00df6bf6’		R

var existingCheckoutId = new System.Guid("a273a0b8-402c-428f-99a0-a93f00df6bf6");

var paysonCheckout = apiCaller.GetCheckout(existingCheckoutId);

Parameter	Type	Description
var existingCheckoutId	Guid		R

Ship/capture checkout

If ($paysonCheckout->status == 'readyToShip') {
    $paysonApi->ShipCheckout($paysonCheckout);
}

if (paysonCheckout.Status == CheckoutStatus.ReadyToShip)
{
    paysonCheckout.Status = CheckoutStatus.Shipped;

    apiCaller.SaveCheckout(paysonCheckout);
}

Cancel checkout

If ($paysonCheckout->status == 'readyToShip') {
    $paysonApi->CancelCheckout($paysonCheckout);
}

if (paysonCheckout.Status == CheckoutStatus.ReadyToShip)
{
    paysonCheckout.Status = CheckoutStatus.Canceled;

    apiCaller.SaveCheckout(paysonCheckout);
}

Update checkout

if ($paysonCheckout->status == 'shipped' || $paysonCheckout->status == 'paidToAccount') {
    foreach ($paysonCheckout->payData->items as $item) {
        // Credit 100%
        $item->creditedAmount = ($item->unitPrice * $item->quantity);

        // Credit 50%
        $item->creditedAmount = (($item->unitPrice * $item->quantity) / 2);

        // Credit specific order item
        if ($item->itemId == '33e67029-c07f-4327-ab2f-a95e00bb764b') {
            $item->creditedAmount = ($item->unitPrice * $item->quantity);
        }
    }

    $paysonCheckout = $paysonApi->UpdateCheckout($paysonCheckout);
}

if (paysonCheckout.Status == CheckoutStatus.Shipped || paysonCheckout.Status == CheckoutStatus.PaidToAccount)
{
    var checkoutItems = paysonCheckout.Order.Items.ToList();
    foreach (var checkoutItem in checkoutItems)
    {
        // Credit 100%
        checkoutItem.CreditedAmount = (checkoutItem.UnitPrice * checkoutItem.Quantity);

        // Credit specific order item
        if (checkoutItem.ItemId == new System.Guid("33e67029-c07f-4327-ab2f-a95e00bb764b"))
        {
            checkoutItem.CreditedAmount = (checkoutItem.UnitPrice * checkoutItem.Quantity);
        }
    }

     apiCaller.SaveCheckout(paysonCheckout);
}

Display checkout

echo $paysonCheckout->snippet;

ViewBag.Snippet = paysonCheckout.Snippet;

@Html.Raw(ViewBag.Snippet)

Minimal example

require_once 'lib/paysonapi.php';

$paysonApi = new PaysonEmbedded\PaysonApi('4', '2acab30d-fe50-426f-90d7-8c60a7eb31d4', true);

$paysonMerchant = new PaysonEmbedded\Merchant('https://www.mystore.com/checkout.php', 'https://www.mystore.com/confirmation.php', 'https://www.mystore.com/notification.php', 'https://www.mystore.com/terms.php');

$payData = new PaysonEmbedded\PayData('SEK');
$payData->AddOrderItem(new PaysonEmbedded\OrderItem('Product Name', 499.00, 1, 0.25, 'MDO0001'));

$checkout = new PaysonEmbedded\Checkout($paysonMerchant, $payData);

$paysonCheckout = $paysonApi->CreateGetCheckout($checkout);

echo $paysonCheckout->snippet;

// Controller
using System.Web.Mvc;
using PaysonIntegrationCO2;
using PaysonIntegrationCO2.Models;
using PaysonIntegrationCO2.Models.Enums;

namespace PaysonCheckout.Controllers
{
    public class CheckoutController : Controller
    {
        public ActionResult Index()
        {
            var apiCaller = new ApiCaller("4", "2acab30d-fe50-426f-90d7-8c60a7eb31d4", true);

            var merchant = new Merchant()
            {
                CheckoutUri = new System.Uri("https://www.mystore.com/checkout"),
                NotificationUri = new System.Uri("https://www.mystore.com/notification"),
                ConfirmationUri = new System.Uri("https://www.mystore.com/confirmation"),
                TermsUri = new System.Uri("https://www.mystore.com/terms")
            };

            var order = new Order()
            {
                Currency = Currency.SEK
            };

            var orderItem = new Item()
            {
                Name = "Product Name",
                Quantity = 1,
                Reference = "MDO0001",
                TaxRate = (decimal)0.25,
                UnitPrice = 499
            };
            order.Items.Add(orderItem);

            var customer = new Customer();

            var gui = new Gui()
            {
                Locale = "sv"
            };

            var checkout = new Checkout()
            {
                Merchant = merchant,
                Order = order,
                Customer = customer,
                Gui = gui
            };
 
            var location = apiCaller.NewCheckout(checkout);

            var paysonCheckout = apiCaller.GetCheckout(location);

            ViewBag.Snippet = paysonCheckout.Snippet;
            
            return View();
        }
    }
}

// View
<html>
    <body>
        @Html.Raw(ViewBag.Snippet)
    </body>
</html>

Full example

// Reference the library
require_once 'lib/paysonapi.php';

// Initiate API
$merchantId = '4';
$apiKey = '2acab30d-fe50-426f-90d7-8c60a7eb31d4';
$environment = true;
$paysonApi = new PaysonEmbedded\PaysonApi($merchantId, $apiKey, $environment);

// Create merchant
$checkoutUri = 'https://www.mystore.com/checkout.php';
$confirmationUri = 'https://www.mystore.com/confirmation.php';
$notificationUri = 'https://www.mystore.com/notification.php';
$termsUri = 'https://www.mystore.com/terms.php';
$partnerId = null;
$integrationInfo = 'PaysonCheckout2.0|1.0|NONE';
$orderReference = 'order123';
$validationUri = 'https://www.mystore.com/validation.php';
$paysonMerchant = new PaysonEmbedded\Merchant($checkoutUri, $confirmationUri, $notificationUri, $termsUri, $partnerId, $integrationInfo);
$paysonMerchant->reference = $orderReference;
$paysonMerchant->validationUri = $validationUri;

// Create order
$currencyCode = 'SEK';
$payData = new PaysonEmbedded\PayData($currencyCode);

// Create order item
$name = 'Product Name';
$unitPrice = 499.00;
$quantity = 1;
$taxRate = 0.25;
$reference = 'MDO0001';
$itemType = 'Physical';
$discountRate = 0.00;
$ean = 1234567891234;
$uri = 'https://www.mystore.com/productpage.php';
$imageUri = 'https://www.mystore.com/images/productimage.jpg';
$orderItem = new PaysonEmbedded\OrderItem($name, $unitPrice, $quantity, $taxRate, $reference, $itemType, $discountRate, $ean, $uri, $imageUri);

// Add order item to order
$payData->AddOrderItem($orderItem);

// Create GUI
$locale = 'sv';
$colorScheme = 'Gray';
$verification = 'none';
$requestPhone = false;
$countries = array('SE', 'DK', 'FI');
$phoneOptional = false;
$gui = new PaysonEmbedded\Gui($locale, $colorScheme, $verification, $requestPhone, $countries, $phoneOptional);

// Create customer
$firstName = 'Tess T';
$lastName = 'Persson';
$email = 'test@payson.se';
$phone = '1111111';
$identityNumber = '4605092222';
$city = 'Stan';
$countryCode = 'SE';
$postalCode = '99999';
$street = 'Storgatan 66';
$type = 'person';
$customer = new PaysonEmbedded\Customer($firstName, $lastName, $email, $phone, $identityNumber, $city, $countryCode, $postalCode, $street, $type);

// Create checkout
$description = 'Order from www.mystore.com';
$expirationTime = '2019-10-22T18:33:27';
$checkout = new PaysonEmbedded\Checkout($paysonMerchant, $payData, $gui, $customer, $description, $expirationTime);

// Get checkout
$paysonCheckout = $paysonApi->CreateGetCheckout($checkout);

// Display checkout
echo $paysonCheckout->snippet;

// Controller
using System.Web.Mvc;
using PaysonIntegrationCO2;
using PaysonIntegrationCO2.Models;
using PaysonIntegrationCO2.Models.Enums;

namespace PaysonCheckout.Controllers
{
    public class CheckoutController : Controller
    {
        public ActionResult Index()
        {

            var paysonMerchantId = "4";
            var paysonApiKey = "2acab30d-fe50-426f-90d7-8c60a7eb31d4";
            var inTestMode = true;
            var apiCaller = new ApiCaller(paysonMerchantId, paysonApiKey, inTestMode);

            var merchant = new Merchant()
            {
                CheckoutUri = new System.Uri("https://www.mystore.com/checkout"),
                NotificationUri = new System.Uri("https://www.mystore.com/notification"),
                ConfirmationUri = new System.Uri("https://www.mystore.com/confirmation"),
                TermsUri = new System.Uri("https://www.mystore.com/terms"),
                PartnerId = "",
                Reference = "order123",
                ValidationUri = new System.Uri("https://www.mystore.com/validation")
            };

            var order = new Order()
            {
                Currency = Currency.SEK
            };

            var orderItem = new Item()
            {
                DiscountRate = (decimal)0.00,
                Name = "Product Name",
                Quantity = 1,
                Reference = "MDO0001",
                TaxRate = (decimal)0.25,
                Type = ItemType.Physical,
                UnitPrice = 499,
                Ean = "1234567891234",
                ImageUri = new System.Uri("https://www.mystore.com/images/productimage.jpg"),
                Uri = new System.Uri("https://www.mystore.com/productpage.php")
            };
            order.Items.Add(orderItem);

            var customer = new Customer()
            {
                FirstName = "Tess T",
                LastName = "Persson",
                Email = "test@payson.se",
                Phone = "1111111",
                IdentityNumber = "4605092222",
                City = "Stan",
                CountryCode = "SE",
                PostalCode = "99999",
                Street = "Storgatan 66",
                Type = CustomerType.Person
            };

            var gui = new Gui()
            {
                RequestPhone = false,
                ColorScheme = ColorScheme.Gray,
                Locale = "sv",
                PhoneOptional = false
            };

            var checkout = new Checkout()
            {
                Merchant = merchant,
                Order = order,
                Customer = customer,
                Gui = gui,
                ExpirationTime = new System.DateTime(2020,08,28,17,44,18)
            };
 
            var location = apiCaller.NewCheckout(checkout);

            var paysonCheckout = apiCaller.GetCheckout(location);

            ViewBag.Snippet = paysonCheckout.Snippet;

            return View();
        }
    }
}

// View
<html>
    <body>
        @Html.Raw(ViewBag.Snippet)
    </body>
</html>

JavaScript Functions

// Reloads the iframe object (for example after updating of an order amount)
function sendUpdate() {
    var iframe = document.getElementById('paysonIframe');
    iframe.contentWindow.postMessage('updatePage', '*');
}

// Lock iframe object from user interaction until checkout is updated
function sendLockDown() {
    var iframe = document.getElementById('paysonIframe');
    iframe.contentWindow.postMessage('lock', '*');
}

// Release an locked iframe object
function sendRelease() {
    var iframe = document.getElementById('paysonIframe');
    iframe.contentWindow.postMessage('release', '*');
}

JavaScript Events

// Sent when customer adress has been set or changed
document.addEventListener("PaysonEmbeddedAddressChanged",function(evt) {
    var address = evt.detail;
        
    //adress.City
    //adress.CountryCode
    //adress.FirstName
    //adress.LastName
    //adress.PostalCode
    //adress.Street
    //adress.Email
        
    // Do something
});

Notifications

After a checkout resource has had its status changed to a status where the merchant may need to act, a notification will be sent. The notification is a simple POST call to the notificationUri specified by the merchant object with the id of the checkout as a querystring parameter.

For example: https://www.mystore.com/notification?checkout=a273a0b8-402c-428f-99a0-a93f00df6bf6

Make sure the notificationUri is publicly accessible for notifications to work.

The POST to notificationUri expect a 200 OK in response and will keep trying for up to 24 hours if the response is anything else.

Notification is sent on status	Description
readyToShip	The payment is complete and the order should be shipped.
shipped	The order has been shipped.
paidToAccount	Money has been paid out to the merchant´s account.
expired	The customer did not complete the payment in time (default 3 hours) or status readyToShip was set for more than 59 days.
canceled	The payment was canceled.
denied	The payment of the order has been denied.

Statuses

Status	Description
created	Set by Payson after the checkout has been created.
readyToPay	Set by Payson after all necessary customer information has been added.
readyToShip	Set by Payson after the customer has completed a payment or when an invoice can be sent.
shipped	Set by the merchant to signal that the order has been shipped.
paidToAccount	Set by Payson when money has been paid out to the merchant´s account.
expired	Set by Payson when expirationTime is reached for a checkout with status created (default 3 hours), or when the status readyToShip has been set for more than 59 days.
canceled	Set by either the merchant or the customer. The customer is able to cancel the order before its status is set to readyToShip. The merchant is able to cancel the order before its status is set to shipped.
denied	Payson will set the status to denied if the purchase is denied for any reason.