Code Samples

Documentation for the Payson Checkout 2.0 libraries hosted at GitHub.

PHP: https://github.com/PaysonAktiebolag/PaysonCheckout2PHP

.NET: https://github.com/PaysonAktiebolag/api-integration-dotnet-co2

Both libraries include complete examples to quickly get you started.

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

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|1.0|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;
$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 R
$quantity integer R
$taxRate float R
$reference string R
$itemType string ‘Physical’, ‘Fee’, ‘Discount’ or ‘Service’. Default ‘Physical’ O
$discountRate float O
$ean integer (13 digits) 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 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 = 'gray';
$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’ or ‘en’. Default ‘sv’ O
$colorScheme string ‘Gray’, ‘Blue’, ‘White’, ‘GrayTextLogos’, ‘BlueTextLogos’, ‘WhiteTextLogos’, ‘GrayNoFooter’, ‘BlueNoFooter’ or ‘WhiteNoFooter’. Default ‘Gray’ 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” or “en” R
ColorScheme PaysonIntegrationCO2.Models.Enums.ColorScheme Gray, Blue, White, GrayTextLogos, BlueTextLogos, WhiteTextLogos, GrayNoFooter, BlueNoFooter or WhiteNoFooter 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 Description
$paysonMerchant PaysonEmbedded\Merchant R
$payData PaysonEmbedded\PayData R
$gui PaysonEmbedded\Gui O
$customer PaysonEmbedded\Customer O
$description 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 Description
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

Update checkout

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

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

if ($existingCheckout->status == 'shipped' || $existingCheckout->status == 'paidToAccount') {
    foreach ($existingCheckout->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($existingCheckout);
}
var existingCheckoutId = new System.Guid("a273a0b8-402c-428f-99a0-a93f00df6bf6");

var paysonCheckout = apiCaller.GetCheckout(existingCheckoutId);

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';
$checkout = new PaysonEmbedded\Checkout($paysonMerchant, $payData, $gui, $customer, $description);

// 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
});

// Sent when purchase is complete
document.addEventListener("PaysonEmbeddedCheckoutResult",function(evt) {
    var result= evt.result;
        
    if(result == 'ReadyToShip') {
         // Do something
    }

    if(result == 'Canceled') {
         // Do something
    }

    if(result == 'Denied') {
         // Do something
    }

    if(result == 'Expired') {
         // 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.
processingPayment Set by Payson when an payment has been initialized and is being processed.
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.
credited Set by either the merchant or by Payson when a purchase has been credited.
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 by any reason.