REST API

Documentation for Payson Checkout 2.0 REST API.

API URLs

Live environment
https://api.payson.se/2.0/
Test environment
https://test-api.payson.se/2.0/

Ensure that all API calls are made with TLS 1.1 or higher.

API endpoints

/Accounts

/Checkouts
/Checkouts/{id}
/Checkouts?{status}

Authentication

The authorization used is basic authentication and you need an Agent ID and an API Key to call these methods.

The Agent ID and an API Key are used to create an auth-string which is used in the message headers to authorize calls.

Auth-string = Base64 representation of “Agent ID:API Key”

Example
Agent ID = 4
API Key = 2acab30d-fe50-426f-90d7-8c60a7eb31d4

Combined these give us a credential string:
4:2acab30d-fe50-426f-90d7-8c60a7eb31d4

Which base64-encoded gives us the auth-string:
NDoyYWNhYjMwZC1mZTUwLTQyNmYtOTBkNy04YzYwYTdlYjMxZDQ=

Get account information

Request

GET https://test-api.payson.se/2.0/Accounts HTTP/1.1
Host: test-api.payson.se
Authorization: Basic NDoyYWNhYjMwZC1mZTUwLTQyNmYtOTBkNy04YzYwYTdlYjMxZDQ=
Content-Type: application/json
Response Codes Status Description
200 Ok The call was successful. The requested resource will be returned in the response body.
401 Unauthorized The authorization failed.

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
   "accountEmail":"testagent-checkout2@payson.se",
   "status":"Approved",
   "merchantId":4,
   "enabledForInvoice":true,
   "enabledForpaymentPlan":true,
   "enabledForRecurringPayments":false
}

Create checkout

Request

POST https://test-api.payson.se/2.0/Checkouts HTTP/1.1
Host: test-api.payson.se
Authorization: Basic NDoyYWNhYjMwZC1mZTUwLTQyNmYtOTBkNy04YzYwYTdlYjMxZDQ=
Content-Type: application/json
{
   "expirationTime": (string, optional),
   "description": (string, optional),
   "customer":{ (customer object, optional)
      "city": (string, optional),
      "countryCode": (string, optional),
      "identityNumber": (string, optional),
      "email": (string, optional),
      "firstName": (string, optional),
      "lastName": (string, optional),
      "phone": (string, optional),
      "postalCode": (string, optional),
      "street": (string, optional),
      "type": (string, optional)
   },
   "order":{ (order object, required)
      "currency": (string, required),
      "items":[ (array, required)
         {
            "name": (string, required),
            "unitPrice": (decimal, required),
            "quantity": (decimal, required),
            "taxRate": (decimal, optional),
            "reference": (string, optional),
            "discountRate": (decimal, optional),
            "ean": (string, optional),
            "imageUri": (string, optional),
            "type": (string, optional),
            "uri": (string, optional)
         }
      ]
   },
   "merchant":{ (merchant object, required)
      "checkoutUri": (string, required),
      "confirmationUri": (string, required),
      "notificationUri": (string, required),
      "termsUri": (string, required),
      "partnerId": (string, optional),
      "validationUri": (string, optional),
      "integrationInfo": (string, optional),
      "reference": (string, optional)
   },
   "gui":{ (gui object, optional)
      "colorScheme": (string, optional),
      "locale": (string, optional),
      "requestPhone": (boolean, optional),
      "phoneOptional": (boolean, optional),
      "verification": (string, optional),
      "countries": (array, optional)
   }
}
{
   "merchant":{
      "checkoutUri":"https://www.examplestore.com/checkout.php",
      "confirmationUri":"https://www.examplestore.com/confirmation.php",
      "notificationUri":"https://www.examplestore.com/notification.php",
      "termsUri":"https://www.examplestore.com/terms.php"
   },
   "order":{
      "currency":"sek",
      "items":[
         {
            "name":"Test product",
            "unitPrice":399.00,
            "quantity":1.00,
            "taxRate":0.25
         }
      ]
   }
}
Response Codes Status Description
201 Created The call was successful. The created resource will be returned in the response body.
400 or 500 Bad request The call failed. Look at the returned JSON-object in the response body for more information.
401 Unauthorized The authorization failed.

Response

HTTP/1.1 201 Created
Location: https://test-api.payson.se/2.0/Checkouts/a273a0b8-402c-428f-99a0-a93f00df6bf6
{
   "status":"created",
   "id":"a273a0b8-402c-428f-99a0-a93f00df6bf6",
   "expirationTime":"2018-08-17T18:33:27",
   "description":null,
   "snippet":"<div id='paysonContainer'  url='https://test-www.payson.se/embedded/checkout?id=a273a0b8-402c-428f-99a0-a93f00df6bf6'></div><script type='text/javascript' src='https://test-www.payson.se/embedded/Content/payson.js?v2'></script>",
   "customer":{
      "city":null,
      "countryCode":null,
      "identityNumber":null,
      "email":null,
      "firstName":null,
      "lastName":null,
      "phone":null,
      "postalCode":null,
      "street":null,
      "type":"person"
   },
   "order":{
      "currency":"sek",
      "totalFeeExcludingTax":11.37,
      "totalFeeIncludingTax":14.21,
      "totalPriceExcludingTax":319.2,
      "totalPriceIncludingTax":399.0,
      "totalTaxAmount":79.8,
      "totalCreditedAmount":0.0,
      "items":[
         {
            "itemId":"8fc9546c-a2db-4584-9d2b-a93f00df6bf6",
            "discountRate":0.0,
            "ean":null,
            "imageUri":null,
            "name":"Test product",
            "quantity":1.0,
            "reference":"product_001",
            "taxRate":0.25,
            "totalPriceExcludingTax":319.2,
            "totalPriceIncludingTax":399.0,
            "totalTaxAmount":79.8,
            "creditedAmount":0.0,
            "type":"physical",
            "unitPrice":399.0,
            "uri":null
         }
      ]
   },
   "merchant":{
      "checkoutUri":"https://www.examplestore.com/checkout.php",
      "confirmationUri":"https://www.examplestore.com/confirmation.php",
      "partnerId":null,
      "notificationUri":"https://www.examplestore.com/notification.php",
      "validationUri":null,
      "termsUri":"https://www.examplestore.com/terms.php",
      "integrationInfo":null,
      "reference":null
   },
   "gui":{
      "colorScheme":"white",
      "locale":"en",
      "requestPhone":false,
      "phoneOptional":false,
      "verification":"none",
      "countries":null
   },
   "history":{
      "created":"2018-08-17T15:33:27.2184344+02:00",
      "readyToPay":null,
      "readyToShip":null,
      "shipped":null,
      "paidToAccount":null,
      "canceled":null,
      "expired":null,
      "denied":null
   },
   "purchaseId":null,
   "links":[
      {
         "href":"https://test-api.payson.se/2.0/Checkouts/a273a0b8-402c-428f-99a0-a93f00df6bf6",
         "rel":"self"
      }
   ]
}

Get checkout

Request

GET https://test-api.payson.se/2.0/Checkouts/a273a0b8-402c-428f-99a0-a93f00df6bf6 HTTP/1.1
Host: test-api.payson.se
Authorization: Basic NDoyYWNhYjMwZC1mZTUwLTQyNmYtOTBkNy04YzYwYTdlYjMxZDQ=
Response Codes Status Description
200 Ok The call was successful. The resource will be returned in the response body.
401 Unauthorized The authorization failed.
404 Not found The requested resource was not found.

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
   "status":"created",
   "id":"a273a0b8-402c-428f-99a0-a93f00df6bf6",
   "expirationTime":"2018-08-17T18:33:27",
   "description":null,
   "snippet":"<div id='paysonContainer'  url='https://test-www.payson.se/embedded/checkout?id=a273a0b8-402c-428f-99a0-a93f00df6bf6'></div><script type='text/javascript' src='https://test-www.payson.se/embedded/Content/payson.js?v2'></script>",
   "customer":{
      "city":null,
      "countryCode":null,
      "identityNumber":null,
      "email":null,
      "firstName":null,
      "lastName":null,
      "phone":null,
      "postalCode":null,
      "street":null,
      "type":"person"
   },
   "order":{
      "currency":"sek",
      "totalFeeExcludingTax":11.37,
      "totalFeeIncludingTax":14.21,
      "totalPriceExcludingTax":319.2,
      "totalPriceIncludingTax":399.0,
      "totalTaxAmount":79.8,
      "totalCreditedAmount":0.0,
      "items":[
         {
            "itemId":"8fc9546c-a2db-4584-9d2b-a93f00df6bf6",
            "discountRate":0.0,
            "ean":null,
            "imageUri":null,
            "name":"Test product",
            "quantity":1.0,
            "reference":"product_001",
            "taxRate":0.25,
            "totalPriceExcludingTax":319.2,
            "totalPriceIncludingTax":399.0,
            "totalTaxAmount":79.8,
            "creditedAmount":0.0,
            "type":"physical",
            "unitPrice":399.0,
            "uri":null
         }
      ]
   },
   "merchant":{
      "checkoutUri":"https://www.examplestore.com/checkout.php",
      "confirmationUri":"https://www.examplestore.com/confirmation.php",
      "partnerId":null,
      "notificationUri":"https://www.examplestore.com/notification.php",
      "validationUri":null,
      "termsUri":"https://www.examplestore.com/terms.php",
      "integrationInfo":null,
      "reference":null
   },
   "gui":{
      "colorScheme":"white",
      "locale":"en",
      "requestPhone":false,
      "phoneOptional":false,
      "verification":"none",
      "countries":null
   },
   "history":{
      "created":"2018-08-17T15:33:27.2184344+02:00",
      "readyToPay":null,
      "readyToShip":null,
      "shipped":null,
      "paidToAccount":null,
      "canceled":null,
      "expired":null,
      "denied":null
   },
   "purchaseId":null,
   "links":[
      {
         "href":"https://test-api.payson.se/2.0/Checkouts/a273a0b8-402c-428f-99a0-a93f00df6bf6",
         "rel":"self"
      }
   ]
}

Update checkout

Request

PUT https://test-api.payson.se/2.0/Checkouts/a273a0b8-402c-428f-99a0-a93f00df6bf6 HTTP/1.1
Host: test-api.payson.se
Authorization: Basic NDoyYWNhYjMwZC1mZTUwLTQyNmYtOTBkNy04YzYwYTdlYjMxZDQ=
Content-Type: application/json
{
   "status":"created",
   "id":"a273a0b8-402c-428f-99a0-a93f00df6bf6",
   "merchant":{
      "checkoutUri":"https://www.examplestore.com/checkout.php",
      "confirmationUri":"https://www.examplestore.com/confirmation.php",
      "notificationUri":"https://www.examplestore.com/notification.php",
      "termsUri":"https://www.examplestore.com/terms.php"
   },
   "order":{
      "currency":"SEK",
      "items":[
         {
            "name":"Test product",
            "unitPrice":399,
            "quantity":1,
            "taxRate":0.25,
            "reference":"product_001"
         },
         { 
            "name":"Test product 2",
            "unitPrice":199,
            "quantity":1,
            "taxRate":0.25,
            "reference":"product_002" 
         }
      ]
   }
}
Response Codes Status Description
200 Ok The call was successful. The updated resource will be returned in the response body.
400 Bad request The call failed. Look at the returned JSON-object in the response body for more information.
401 Unauthorized The authorization failed.

Response

HTTP/1.1 200 OK
Location: https://test-api.payson.se/2.0/Checkouts/a273a0b8-402c-428f-99a0-a93f00df6bf6
Content-Type: application/json
{
   "status":"created",
   "id":"a273a0b8-402c-428f-99a0-a93f00df6bf6",
   "expirationTime":"2018-08-17T18:33:27",
   "description":null,
   "snippet":"<div id='paysonContainer'  url='https://test-www.payson.se/embedded/checkout?id=a273a0b8-402c-428f-99a0-a93f00df6bf6'></div><script type='text/javascript' src='https://test-www.payson.se/embedded/Content/payson.js?v2'></script>",
   "customer":{
      "city":null,
      "countryCode":null,
      "identityNumber":null,
      "email":null,
      "firstName":null,
      "lastName":null,
      "phone":null,
      "postalCode":null,
      "street":null,
      "type":"person"
   },
   "order":{
      "currency":"sek",
      "totalFeeExcludingTax":17.04,
      "totalFeeIncludingTax":21.3,
      "totalPriceExcludingTax":478.4,
      "totalPriceIncludingTax":598,
      "totalTaxAmount":119.6,
      "totalCreditedAmount":0.0,
      "items":[
         {
            "itemId":"8fc9546c-a2db-4584-9d2b-a93f00df6bf6",
            "discountRate":0.0,
            "ean":null,
            "imageUri":null,
            "name":"Test product",
            "quantity":1.0,
            "reference":"product_001",
            "taxRate":0.25,
            "totalPriceExcludingTax":319.2,
            "totalPriceIncludingTax":399.0,
            "totalTaxAmount":79.8,
            "creditedAmount":0.0,
            "type":"physical",
            "unitPrice":399.0,
            "uri":null
         },
         {
            "itemId":"7840ed17-b110-4d15-b021-a94a00cfb6ae",
            "discountRate":0.0,
            "ean":null,
            "imageUri":null,
            "name":"Test product 2",
            "quantity":1.0,
            "reference":"product_002",
            "taxRate":0.25,
            "totalPriceExcludingTax":159.2,
            "totalPriceIncludingTax":199,
            "totalTaxAmount":39.8,
            "creditedAmount":0.0,
            "type":"physical",
            "unitPrice":199,
            "uri":null
          }
      ]
   },
   "merchant":{
      "checkoutUri":"https://www.examplestore.com/checkout.php",
      "confirmationUri":"https://www.examplestore.com/confirmation.php",
      "partnerId":null,
      "notificationUri":"https://www.examplestore.com/notification.php",
      "validationUri":null,
      "termsUri":"https://www.examplestore.com/terms.php",
      "integrationInfo":null,
      "reference":null
   },
   "gui":{
      "colorScheme":"white",
      "locale":"en",
      "requestPhone":false,
      "phoneOptional":false,
      "verification":"none",
      "countries":null
   },
   "history":{
      "created":"2018-08-17T15:33:27.2184344+02:00",
      "readyToPay":null,
      "readyToShip":null,
      "shipped":null,
      "paidToAccount":null,
      "canceled":null,
      "expired":null,
      "denied":null
   },
   "purchaseId":null,
   "links":[
      {
         "href":"https://test-api.payson.se/2.0/Checkouts/a273a0b8-402c-428f-99a0-a93f00df6bf6",
         "rel":"self"
      }
   ]
}

List checkouts

Request

GET https://test-api.payson.se/2.0/Checkouts?status=PaidToAccount HTTP/1.1
Host: test-api.payson.se
Authorization: Basic NDoyYWNhYjMwZC1mZTUwLTQyNmYtOTBkNy04YzYwYTdlYjMxZDQ=
Content-Type: application/json
Response Codes Status Description
200 Ok The call was successful. The requested resource will be returned in the response body.
400 Bad request The call failed. Look at the returned JSON-object in the response body for more information.
401 Unauthorized The authorization failed.

Response

HTTP/1.1 200 OK
Location: https://test-api.payson.se/2.0/Checkouts/a273a0b8-402c-428f-99a0-a93f00df6bf6
Content-Type: application/json
{
   "pageSize":20,
   "page":1,
   "totalPages":1,
   "count":2,
   "totalCount":2,
   "data":[
      {
         "status":"paidToAccount",
         "id":"a77ad00c-bf5a-4b1b-a26b-a6d30127e59b",
         "expirationTime":"2016-12-05T20:58:05",
         "description":"",
         "snippet":"",
         "customer":{
            "city":"Stan",
            "countryCode":"SE",
            "identityNumber":"4605092222",
            "email":"test@test.com",
            "firstName":"Tess T",
            "lastName":"Persson",
            "phone":null,
            "postalCode":"99999",
            "street":"Testgatan 1",
            "type":"person"
         },
         "order":{
            "currency":"sek",
            "totalFeeExcludingTax":13.68,
            "totalFeeIncludingTax":17.10,
            "totalPriceExcludingTax":381.82,
            "totalPriceIncludingTax":480.00,
            "totalTaxAmount":98.18,
            "totalCreditedAmount":0.00,
            "items":[
               {
                  "itemId":"0b3ab15b-8a4b-44ff-86d7-a6d30127e59b",
                  "discountRate":0.0000,
                  "ean":null,
                  "imageUri":null,
                  "name":"discount",
                  "quantity":1.00,
                  "reference":"a",
                  "taxRate":0.10,
                  "totalPriceExcludingTax":-18.18,
                  "totalPriceIncludingTax":-20.00,
                  "totalTaxAmount":-1.82,
                  "creditedAmount":0.00,
                  "type":"discount",
                  "unitPrice":-20.00,
                  "uri":null
               },
               {
                  "itemId":"638fbfa0-2031-435d-b5ac-a6d30127e59b",
                  "discountRate":0.0000,
                  "ean":"ean12345",
                  "imageUri":"http://imageUri",
                  "name":"Test product",
                  "quantity":1.00,
                  "reference":"MD0",
                  "taxRate":0.25,
                  "totalPriceExcludingTax":400.00,
                  "totalPriceIncludingTax":500.00,
                  "totalTaxAmount":100.00,
                  "creditedAmount":0.00,
                  "type":"physical",
                  "unitPrice":500.00,
                  "uri":"http://uri"
               }
            ]
         },
         "merchant":{
            "checkoutUri":"http://my.local/phpAPI/example/checkout.php",
            "confirmationUri":"http://my.local/phpAPI/example/confirmation.php",
            "partnerId":null,
            "notificationUri":"http://my.local/phpAPI/example/notification.php",
            "validationUri":null,
            "termsUri":"http://my.local/phpAPI/example/terms.php",
            "integrationInfo":"PaysonCheckout2.0|1.0|NONE",
            "reference":null
         },
         "gui":{
            "colorScheme":"blue",
            "locale":"sv",
            "requestPhone":false,
            "phoneOptional":false,
            "verification":"none",
            "countries":null
         },
         "history":{
            "created":"2016-12-05T17:57:19",
            "readyToPay":"2016-12-05T17:57:31",
            "readyToShip":"2016-12-05T17:57:34",
            "shipped":"2016-12-05T17:58:05",
            "paidToAccount":"2016-12-05T17:59:37",
            "canceled":null,
            "expired":null,
            "denied":null
         },
         "purchaseId":3758834,
         "links":[
            {
               "href":"https://test-api.payson.se/2.0/Checkouts/a77ad00c-bf5a-4b1b-a26b-a6d30127e59b",
               "rel":"self"
            }
         ]
      },
      {
         "status":"paidToAccount",
         "id":"e70ef52e-f775-41ad-826b-a8b000baf48d",
         "expirationTime":"2018-03-27T16:22:57",
         "description":"",
         "snippet":"",
         "customer":{
            "city":"Stan",
            "countryCode":"SE",
            "identityNumber":"4605092222",
            "email":"test@payson.se",
            "firstName":"Tess T",
            "lastName":"Persson",
            "phone":"1111111",
            "postalCode":"99999",
            "street":"Testgatan 1",
            "type":"person"
         },
         "order":{
            "currency":"sek",
            "totalFeeExcludingTax":4.50,
            "totalFeeIncludingTax":5.63,
            "totalPriceExcludingTax":42.00,
            "totalPriceIncludingTax":52.50,
            "totalTaxAmount":10.50,
            "totalCreditedAmount":52.50,
            "items":[
               {
                  "itemId":"6c77e58b-1371-4189-80be-a8b000baf48d",
                  "discountRate":0.0000,
                  "ean":null,
                  "imageUri":null,
                  "name":"Blouse S, Black",
                  "quantity":1.00,
                  "reference":"2",
                  "taxRate":0.25,
                  "totalPriceExcludingTax":27.00,
                  "totalPriceIncludingTax":33.75,
                  "totalTaxAmount":6.75,
                  "creditedAmount":33.75,
                  "type":"physical",
                  "unitPrice":33.75,
                  "uri":null
               },
               {
                  "itemId":"00136ad4-adc9-4fec-a3af-a8b000baf48d",
                  "discountRate":0.0000,
                  "ean":null,
                  "imageUri":null,
                  "name":"PS1.6.0.14 Demo",
                  "quantity":1.00,
                  "reference":"Frakt",
                  "taxRate":0.25,
                  "totalPriceExcludingTax":15.00,
                  "totalPriceIncludingTax":18.75,
                  "totalTaxAmount":3.75,
                  "creditedAmount":18.75,
                  "type":"service",
                  "unitPrice":18.75,
                  "uri":null
               }
            ]
         },
         "merchant":{
            "checkoutUri":"http://localhost/prestashop16014/sv/index.php?controller=order?step=3",
            "confirmationUri":"http://localhost/prestashop16014/sv/module/paysoncheckout2/confirmation?trackingId=1522149640&id_cart=19&call=confirmation",
            "partnerId":null,
            "notificationUri":"http://localhost/prestashop16014/sv/module/paysoncheckout2/notifications?trackingId=1522149640&id_cart=19&call=notification",
            "validationUri":null,
            "termsUri":"http://localhost/prestashop16014/sv/content/3-terms-and-conditions-of-use",
            "integrationInfo":"payson_checkout2_prestashop16|2.0.8|1.6.0.14",
            "reference":"19"
         },
         "gui":{
            "colorScheme":"whiteNoFooter",
            "locale":"SV",
            "requestPhone":true,
            "phoneOptional":false,
            "verification":"none",
            "countries":[
               "SE",
               "GB"
            ]
         },
         "history":{
            "created":"2018-03-27T13:20:40",
            "readyToPay":"2018-03-27T13:20:47",
            "readyToShip":"2018-03-27T13:20:54",
            "shipped":"2018-03-27T13:22:37",
            "paidToAccount":"2018-03-27T13:22:58",
            "canceled":null,
            "expired":null,
            "denied":null
         },
         "purchaseId":3793110,
         "links":[
            {
               "href":"https://test-api.payson.se/2.0/Checkouts/e70ef52e-f775-41ad-826b-a8b000baf48d",
               "rel":"self"
            }
         ]
      }
   ],
   "links":[
      {
         "href":"https://test-api.payson.se/2.0/Checkouts?merchantId=4&page=1&status=PaidToAccount",
         "rel":"self"
      }
   ]
}

Parameters

R = Required, O =  Optional

Parameter Type Description
checkout
id UUID Unique identifier of the checkout. Read only
purchaseId Null/int Unique identifier of Payson payment. Null until status changes to readyToShip. Read only
description String Used to describe the purchase. O
snippet String (HTML) HTML-snippet. Read only
status String Status of the checkout. O
expirationTime Date and time (ISO 8601) Expiration time of the checkout. O (default 3 hours)
merchant Merchant resource. R
customer Customer resource. O
order Order resource. R
gui Gui resource. O
history History resource. Read only
merchant
checkoutUri URI URI to the merchants checkout page. R
confirmationUri URI URI to the merchants confirmation page. R
notificationUri URI Notification URI which receives status updates. R
termsUri URI URI to the merchants terms page. R
validationUri URI Validation URI which is called 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. Make sure the URI is publicly accessible. O
integrationInfo String (max 100) Information about the integration. O
partnerId String (max 100) Partners unique identifier. Only applicable for certain merchants. If you haven’t received a partnerId from Payson then you don’t use this parameter O
reference String (max 100) Merchants own reference of the checkout. Can for example be used for your order id. O
customer
city String (max 100) O
countryCode String (max 2) O
identityNumber String (max 20) O
email String (max 100) O
firstName String (max 100) O
lastName String (max 100) O
phone String (max 20) O
postalCode String (max 20) O
street String (max 100) O
type String Can be ‘person’ or ‘business’. O (default ‘person’)
order
currency String (currency) Can be ‘sek’ or ‘eur’. R
items Array (order items) Order items. R
totalPriceExcludingTax Decimal number (2 decimals) Total price of the order excluding taxes. Read only
totalPriceIncludingTax Decimal number (2 decimals) Total price of the order including taxes. Read only
totalFeeExcludingTax Decimal number (2 decimals) Total fee of the order excluding taxes. Read only
totalFeeIncludingTax Decimal number (2 decimals) Total fee of the order including taxes. Read only
totalTaxAmount Decimal number (2 decimals) Total taxes of the order. Read only
totalCreditedAmount Decimal number (2 decimals) Total credited amount of the order. Read only
items
discountRate Decimal number (0.00-1.00) Discount rate of the article. O
creditedAmount Decimal number (2 decimals) Credited amount. Can only be set after an order has been shipped. (O)
ean String (8-18) European Article Number. O
imageUri URI A URI to an image of the article O
itemId UUID Unique number used to identify the item. Will be assigned by Payson during the creation of an order. O
name String (max 200) Name of the article. R
quantity Integer Quantity of the article. R
reference String (max 100) Article reference, usually the article number. R
taxRate Decimal number (0.00-1.00) Tax rate of the article. O
totalPriceExcludingTax Decimal number (2 decimals) Total price of the article excluding tax. Read only
totalPriceIncludingTax Decimal number (2 decimals) Total price of the article including tax. Read only
totalTaxAmount Decimal number (2 decimals) Total tax of the article. Read only
type String Type of article. Can ‘physical’, ‘discount’, ‘fee’ or ‘service’. O (default ‘physical’)
unitPrice Decimal number (2 decimals) Unit price of the article including tax. 2 decimals, make sure all tax rounding is done before sending to Payson. R
uri URI URI to a page with information about the item (product page). O
gui
colorScheme String Color scheme of the checkout snippet. Can be ‘Gray’ or ‘White’. O (default ‘white’)
locale String (locale) Language of the checkout snippet. Can be ‘sv’, ‘en’, ‘fi’, ‘no’, ‘da’, ‘es’ or ‘de’. O (default ‘en’)
requestPhone Bool Used to require the user to fill in his phone number. O (default false)
phoneOptional Bool Used to ask the user to fill in his phone number, but not strict required. O (default false)
countries Array List of countries a customer can choose in the checkout snippet.
Case sensitive, e.g use: [“SE”, “GB”, “DK”]
O (default null will list all countries)
verification String Used to enable BankID verification. Can be ‘none’ or ‘bankid’. O (default ‘none’)
history
created Date and time (ISO 8601) Time the status was set to Created. Read only
readyToPay Date and time (ISO 8601) Time the status was set to ReadyToPay. Read only
readyToShip Date and time (ISO 8601) Time the status was set to ReadyToShip. Read only
shipped Date and time (ISO 8601) Time the status was set to Shipped. Read only
paidToAccount Date and time (ISO 8601) Time the status was set to PaidToAccount. Read only
canceled Date and time (ISO 8601) Time the status was set to Canceled. Read only
expired Date and time (ISO 8601) Time the status was set to Expired. Read only
denied Date and time (ISO 8601) Time the status was set to Denied. Read only

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;
        
    //console.log(adress.City);
    //console.log(adress.CountryCode);
    //console.log(adress.FirstName);
    //console.log(adress.LastName);
    //console.log(adress.PostalCode);
    //console.log(adress.Street);
    //console.log(adress.Email);

});

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 POST HTTP 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.

HTTP/1.1 200 OK
Notification is sent when The checkout will have status
The checkout is complete and the order should be shipped. readyToShip
The checkout has been marked as shipped. shipped
Money has been paid out to the merchant´s PaysonAccount. paidToAccount
The customer did not complete the checkout in time (default 3 hours) or status readyToShip was set for more than 59 days. expired
The checkout was canceled. canceled
The checkout has been fully credited. paidToAccount*
The checkout has been partially credited. shipped*

*Check totalCreditedAmount to determine if the checkout has been credited.

Merchant Validation

If there is a need to validate the order before payment is done the validationUri can be used. This is an optional parameter.
Validation can for example be used to make sure all products are still in stock before the payment is done.Payson will call the validationUri when the user clicks the “Complete purchase” button.

The call is a GET HTTP request with the checkout ID added as a querystring parameter.

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

For an approved order the merchant must respond with HTTP status 200 OK for the payment flow to continue as normal.

HTTP/1.1 200 OK

To deny the purchase respond with a HTTP status 303 See Other and a Location header with the URI to where the customer will be redirected.

HTTP/1.1 303 See Other
Location: https://www.mystore.com/information-page

The URI provided in the Location header is where the merchant informs the customer about why the purchase was stopped and what the customer should do to continue.

It is very important to make sure the validationUri is publicly accessible for validation to work.