Payson 1.0

Payson 1.0 payment page opens in a new tab/window.


Libraries are hosted at GitHub.

This is a library for Payson 1.0.
Code examples for this library are included in the example folder.

The library include a complete demo store to get you started, visit code samples for examples using this library.

Demo Stores

API Demo Store Payson 1.0

Example of the basic demo store that is
included in the .NET library.

Demo Store »

PrestaShop 1.7

Demo Store »


Demo Store »


PrestaShop 1.7

Get module »

PrestaShop 1.6

Get module »

OpenCart 3.0

Get module »

OpenCart 2.3

Get module »

OpenCart 2.0

Get module »

Developed, sold and supported by Krokedil

Buy plugin »

Developed, sold and supported by nop4you

Buy module by nop4you »

Developed, sold and supported by Crona Service

Buy module by Crona Service »

Payment Options

SEK – Invoice, Payment plan, Card (Visa, MasterCard), Direct payment by bank, PaysonAccount
EUR – Card (Visa, MasterCard), Direct payment by bank, PaysonAccount


The payment methods displayed will be different depending on the parameters sent in the pay-request. The payment page is responsive and will be optimized for the device used by your customer.


A separate test system is available that can be used to test your integration. It has the same functionality as the live API including IPN, but no real money will be moved. For bank and credit card payments a bank simulation page will be shown in place of the live bank page which allow you to simulate an approved or denied bank response.

Test Agent & Customer

The test system does not share accounts with the live site. A test agent has been setup that can be used in place of the live agent account. The agent is approved for both credit card/bank payments and invoice payments.

API User ID (AgentId):4
API Password (MD5-key):2acab30d-fe50-426f-90d7-8c60a7eb31d4

Important: The test credentials can only be used when initiating a test transaction i.e. when communicating with and Any attempt to use these credentials with the production environment will result in failed authentication (ERROR 520003).

For more detailed testing you may create your own test agent for use in the test environment. Create your own test agent here. This test agent will be automatically approved for both credit card/bank payments and invoice payments. Using your own test agent makes it possible for you to login to that TestAccount (on the test enironment) and see the requestlogs for your test agent.

Any credit card with a valid checksum digit and valid prefix will work for test transactions. The card will not be charged.

Any customer email and first/last name will work, but it is also possible to use our predefined test customer.

Customer Email:
Method/ActionTest URL
Pay Forward URL{token}
Pay Endpoint
PaymentDetails Endpoint
PaymentUpdate Endpoint
Validate Endpoint
AccountInfo Endpoint

Limitations of the test environment

There are several limitations and differences in the test environment compared to the live system.

  • No emails will be sent. All email functionality is completely disabled.
  • Test info box. A info box will be displayed on most pages to make you aware that it is the test environment.
  • No Account page for Payson’s test agent If you use Payson’s test agent with AgentId 4 it is not possible to login on the site and see the account information such as the history of payments made in the test environment. However, if you create your own test agent you may login to and see all transactions and API requests there.
  • Missing functionality. Not all functionality is available in the TestAccount

Testing on the live API

It is recommended that you also do some tests in the live API when your integration is complete to verify that everything is setup correctly including the action URLs.

The easiest way to minimize the fees involved for card and bank payments is to refund the payment. The refund function can be reached from the payment history details page in the account.

In the case of invoices no fees and no actual invoices are issued until you mark them as shipped and shipped invoices can be credited.

API Overview

Actions are initiated by sending an HTTP POST request to one of Paysons endpoint URIs.
The response from the Payson server contain information about the overall success of the request and possible additional data depending on which action was requested.The following diagram shows the basic request-response mechanism:

Request - response mechanism

HTTP Headers

Headers are used to specify API credentials and HTTP content type. The following HTTP Headers can/must be submitted with each request to Payson:

RequiredPAYSON-SECURITY-PASSWORDYour API Password (MD5-key).
RequiredContent-TypeValue must be: application/x-www-form-urlencoded
OptionalPAYSON-APPLICATION-IDYour Application ID. (Only applicable if you have received one)

HTTP Message body

The message body is used to provide parameters needed to complete the requested action. The parameter list must be formatted as a list of Name-Value pairs (NVP formatted) separated by the ampersand (&) sign, i.e. must be in the form ‘NAME_1=VALUE_1&NAME_2=VALUE_2&…&NAME_N=VALUE_N’.

HTTP response

In all cases except for the ‘Validate’ action, the HTTP response message body consists of an NVP-formatted string as described above. Each NVP-formatted string has parameters that describe the overall success of the requested action, as well as possible additional parameters specific to the requested action.

Forward URL

After you have received a token, redirect the customer to the following url to complete the payment:{token}


All requests to the Payson API servers are made over HTTPS using 128-bit encryption. The requests are routed through the sub domain, for which SecureTrust CA has signed the certificate.
Your API credentials must be provided in every request to Payson in order to be valid.

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

Payment Token

You will receive a payment reference, or ‘payment token’, from an initial pay action. The token will be used in most of subsequent requests to Payson regarding that payment. A typical example of this would be:

Execution flow between your site and Payson

API Action Pay

Actions are initiated by sending HTTP POST requests to endpoint URIs located at Paysons servers.

Initializes a payment request.

API method: POST

API endpoint:

RequiredParameterData typeDescription
RequiredreturnUrlstring (2048)URL to which the customer’s browser is redirected after the payment is completed.Note: This includes both successful and unsuccessful payments.
RequiredcancelUrlstring (2048)URL to which the customer is redirected if the payment is manually canceled by the user before it is completed.
RecommendedipnNotificationUrlstring (2048)The URL for receiving an Instant Payment Notification about this payment.Note: This parameter has been made optional due to backward compatability. Read more about the use of it here »
Requiredmemostring (128)Description of items the customer is purchasing.
RequiredsenderEmailstring (128)Email address of the person sending money. This is the Payson account where the settled amount is transferred from.
OptionalsenderFirstNamestring (128)First name of the buyer as entered during checkout.
OptionalsenderLastNamestring (128)Last name of the buyer as entered during checkout.
OptionallocaleCodeLocaleCodeLocale of pages displayed by Payson during payment.
Default: SV
OptionalcurrencyCodeCurrencyCodeThe currency used for the payment.
Default: SEK
OptionalfundingList.fundingConstraint (0..N).constraintFundingConstraintSpecifies a list of allowed funding options for the payment.
If this field is omitted, the payment can be funded by any funding type that is supported for the merchant (excluding invoice).
OptionalinvoiceFeedecimalAn invoice fee that will be added as an order item.

  • Must be in the range 0 to 40

Note: This amount should be included in amount specified for the primary receiver

Optionalcustomstring (256)A free-form field for your own use. This will be returned in requests to the PaymentDetails API endpoint.
OptionaltrackingIdstring (128)Your own tracking id. This will be returned in requests to the PaymentDetails API endpoint.
OptionalguaranteeOfferedGuaranteeOfferedWhether Payson Guarantee is offered or not.
OptionalshowReceiptPageboolWhether to show the receipt page in Paysons 1.0. Default: true
Receiver Details

The list of receivers. If you have more than one receiver you must specify exactly one as primary.

RequiredreceiverList.receiver (0..N).emailstring (128)Email address of the receiver.
RequiredreceiverList.receiver (0..N).amountdecimalThe amount (including VAT) to transfer to this recipient.Note: If you have more than one receiver, the primary receiver’s amount must still be the full amount of the payment.
OptionalreceiverList.receiver (0..N).primaryboolWhether this receiver is the primary receiver. This only applies if there is more than one receiver.
Order Item Details
Note: Order Items are required for Invoice, and optional for all other payments types.
RequiredorderItemList.orderItem (0..N).descriptionstring (128)Description of this item.
RequiredorderItemList.orderItem (0..N).skustring (128)SKU of this item.
RequiredorderItemList.orderItem (0..N).quantitydecimalQuantity of this item.
RequiredorderItemList.orderItem (0..N).unitPricedecimalThe unit price of this item not including VAT. Can also be a negative amount for a discount.
RequiredorderItemList.orderItem (0..N).taxPercentagedecimalTax percentage for this item.
Note: Must be a decimal value and not an actual percentage. E.g. for a 25% tax percentage use 0.25.

Pay Response Parameters

ParameterData typeDescription
responseEnvelope.ackAckCodeAcknowledge code indicating the overall success of the request.
responseEnvelope.timestampDateTimeTimestamp that identifies when the response was sent.
responseEnvelope.correlationIdNot used
TOKENGuidA token by which you identify to Payson that you are processing this payment.

API Action PaymentDetails

Get details about an existing payment.

API method: POST

API endpoint:

PaymentDetails request parameters

RequiredParameterData typeDescription
RequiredtokenGuidThe token obtained when creating the payment.

PaymentDetails Response Parameters

ParameterData typeDescription
responseEnvelope.ackAckCodeAcknowledge code indicating the overall success of the request.
responseEnvelope.timestampDateTimeTimestamp that identifies when the response was sent.
responseEnvelope.correlationIdNot used
purchaseIdintPayson purchaseId for this payment.
senderEmailstringThe sender’s email address.
statusPaymentStatusThe status of the payment.
typePaymentTypeType of payment.
guaranteeStatusGuaranteeStatusThe status of an ongoing Payson Guarantee payment. This is only set if type is GUARANTEE.
guaranteeDeadlineTimestampDateTimeTimestamp that identifies when the next guarantee deadline is due, if one exists.
invoiceStatusInvoiceStatusThe status of an ongoing Payson Invoice payment. This is only set if type is INVOICE.
customstringA free-form field submitted with the Pay request.
trackingIdstringYour own invoice or tracking id submitted with the Pay request.
receiverList.receiver(n).emailstringEmail address of the receiver.
receiverList.receiver(n).amountstringThe amount to transfer to this receiver.
receiverList.receiver(n).primaryboolDetermines whether this is the primary receiver or not.
currencyCodeCurrencyCodeA three-character currency code.
receiverFeedecimalThe fee charged the receiver of the payment
orderItemList.orderItem(n).descriptionstringOrder item description, if set.
orderItemList.orderItem(n).unitPricedecimalOrder item unit price, if set.
orderItemList.orderItem(n).quantitydecimalOrder item quantity, if set.
orderItemList.orderItem(n).taxPercentagedecimalOrder item tax percentage, if set.
orderItemList.orderItem(n).skustringOrder item SKU, if set.

Shipping address

Shipping address info. Only set if the type is INVOICE and invoiceStatus is one of ORDERCREATED, SHIPPED, DONE or CREDITED. Please note that this address must be used as shipping address.

ParameterData typeDescription
shippingAddress.namestringThe name of the shipment’s receiver.
shippingAddress.streetAddressstringThe shipment receiver’s street address.
shippingAddress.postalCodestringThe shipment receiver’s postal code.
shippingAddress.citystringThe shipment receiver’s city.
shippingAddress.countrystringThe shipment receiver’s country.

API Action PaymentUpdate

Update an existing payment, for instance mark an order as shipped or canceled. The following updating actions are available:

  • CANCELORDER – Cancel a payment before it is shipped.
    Note: Possible if type is INVOICE and invoiceStatus is ORDERCREATED.
  • SHIPORDER – Mark an invoice payment as shipped (capture payment). The sender will be notified by Payson that an invoice has been created.
    Note: Possible if type is INVOICE and invoiceStatus is ORDERCREATED.
  • CREDITORDER – Credit an invoice payment.
    Note: If the receiver account has insufficient funds it is not possible to credit the order. Possible if type is INVOICE and invoiceStatus is SHIPPED or DONE.
  • REFUND – Refunds a bank or card payment to the sender. If the sender deposited the amount it will be refunded to the origin if the origin supports it. If the sender payment was made in full or partially with funds from the sender’s Payson account the credited amount will be refunded to the sender’s Payson account.
    Note: Possible if type is TRANSFER.
  • CANCELPAYMENT – Cancels a pending bank or card payment.
    Note: Possible if type is TRANSFER.

API method: POST

API endpoint:

PaymentUpdate request parameters

RequiredParameterData typeDescription
RequiredtokenGuidThe token obtained when creating the payment.
RequiredactionUpdateActionAction to take for this payment.

PaymentUpdate Response Parameters

ParameterData typeDescription
responseEnvelope.ackAckCodeAcknowledge code indicating the overall success of the request.
responseEnvelope.timestampDateTimeTimestamp that identifies when the response was sent.
responseEnvelope.correlationIdNot used

API Action Validate

This method is used to validate the content of the IPN message that was sent to your ipnNotificationUrl.

API method: POST

API endpoint:

Validate request parameters

Send the complete unaltered IPN message back to Payson; the message must contain the same parameters in the same order and be encoded in the same way as the original message.

Validate Response Parameters

A single-word message (Note: NOT an NVP message) is returned. One of the following values is used as content:

  • VERIFIED – Message is valid
  • INVALID – Message is invalid or altered in some way

After you receive the VERIFIED message, there are other important checks you should perform. For instance, confirm that the payment status is COMPLETED for bank and card payments and Payson Guarantee payments. For invoice payment, make sure the invoiceStatus is ORDERCREATED. You should also verify that the payment has not already been processed in your system.

It is also a good idea to validate that the receiver’s email address is registered to you and that the price, item description, and so on match the transaction on your website.

API Action AccountInfo

This method is used to validate API credentials and get basic information about API account.

API method: POST

API endpoint:

AccountInfo request parameters

No additional parameters should be sent.
For some curl requests it might be necessary to set ‘Content-Length: 0’ in header.

AccountInfo Response Parameters

ParameterData typeDescription
responseEnvelope.ackAckCodeAcknowledge code indicating the overall success of the request.
responseEnvelope.timestampDateTimeTimestamp that identifies when the response was sent.
responseEnvelope.correlationIdNot used
accountEmailstringPayson account email attached to request agent.
statusstringApproved or Denied.
merchantIdintAgent Id.
enabledForInvoiceboolIs agent enabled to receive invoice payments
enabledForpaymentPlanboolIs agent enabled to receive payment plan payments

Data Types


For all decimals used, the decimal separator must be a period (.)


A 38 characters long globally unique identifier.


Must be one of the following values:

  • NO


Must each be one of the following values:

  • BANK


Must be one of the following values:

  • SEK
  • EUR


Must be one of the following values:

  • SV
  • EN
  • FI
  • DK
  • NO




  • TRANSFER – This is a bank or card payment.
  • GUARANTEE – This is a Payson Guarantee payment.
  • INVOICE – This is an invoice payment.


Note: for invoice and Guarantee payments the corresponding statuses (InvoiceStatus and GuaranteeStatus) should be used.

  • CREATED – The payment request was received and has been created in Payson’s system. Funds will be transferred once approval is received.
  • PENDING – The sender has a pending transaction. A guarantee payment in progress has status pending. Please check guaranteeStatus for further details.
  • PROCESSING – The payment is in progress, check again later.
  • COMPLETED – The sender’s transaction has completed.
  • CREDITED – The sender’s transaction has been credited.
  • INCOMPLETE – Obsolete, this status is not used anymore.
  • ERROR – The payment failed and all attempted transfers failed or all completed transfers were successfully reversed.
  • REVERSALERROR – One or more transfers failed when attempting to reverse a payment.
  • ABORTED – The payment was aborted before any money were transferred.




It can be one of the following values:

  • PENDING – The invoice is not created yet. Please note that this does not mean that an invoice will be approved, this is only a temporary status until the transaction is settled.
  • ORDERCREATED – The customer was accepted for invoice purchase and an order has been created.
  • CANCELED – The order was canceled by the customer.
  • SHIPPED – The order has been converted to an invoice.
  • DONE – The money has been transferred to the receiver’s Payson account.
  • CREDITED – The sender’s transaction has been credited.
  • DENIED – No invoice was created.


Must be one of the following values:


Error Codes

Error Response Parameters

This section details the possible errors you can receive in a request to a Payson API server.

errorList.error(n).errorIdA number that uniquely identifies an error.
errorList.error(n).messageA description of errorId.
errorList.error(n).parameterIndicates which submitted parameter caused the error. Only included where appropriate.
500000System error.
520002Internal error.
520003Authentication failed; Credentials were not valid.
520005The merchant account is locked.
539041An email account is not receive enabled.
579008Number of primary receivers exceeds 1.
579009If PaysonGuarantee is offered, there may be at most one receiver
580021Invalid parameter – too long.
580022Your request was invalid. Check the parameter of the error to see which is invalid.
580028A URL supplied with the request is malformed.
580029A required parameter was not provided. Check the error parameter list.
580030The amount is below the minimum limit.
580031The amount is above the maximum limit.
589018Invalid payment token
589053All payment methods have been disabled for this combination of funding constraint, merchant and receiver.
590001The total amount specified for receivers does not match the total amount specified by the order items.
590005Not all related order item parameters where specified. All or none of unitPrice, quantity, taxPercentage and sku must be set.
590006Invoice requires one receiver.
590008Invoice requires that order items are specified.
590009Invoice payments are not available to this merchant.
590010The requested action is not possible in the current state of the payment.
590011The amount on the invoice is below the minimum limit.
590012Invoice does not support the selected currency.
590013The invoice fee out of the valid range.
590015The receiver is not allowed to receive invoices.
590016The sender and receiver is the same user.
590018The requested action is not possible for the current type of payment.
590020A primary receiver is required for this kind of payment.

Notifications (IPN)

IPN is a message service that notifies you of events related to Payson payments as they happen. You can use it to automate back-office and administrative functions, such as fulfilling orders, tracking customers, or providing information related to a payment.

ipnNotificationUrl Callback

An IPN message is sent to the URL specified in the ipnNotificationUrl field of the Pay request when the payment changes its state.

An IPN message consists of the same NVP formatted content as a request to PaymentDetails will give and a hash parameter. It will not include the response envelope parameters.

Must use port 80 or 443 (the standard http and https ports)

The IPN protocol consists of three steps:

  1. Payson sends your IPN listener a message that notifies you of the event.
  2. Your listener sends the complete unaltered message back to Payson; the message must contain the same parameters in the same order and be encoded in the same way as the original message.
  3. Payson sends a single word back, which is either VERIFIED if the message originated from Payson or INVALID if there is any discrepancy with what was originally sent.

After successfully completing the protocol, your back-office or administrative process can use the contents of the IPN message and respond appropriately. For example, the IPN message may trigger your system to print shipping labels for items whose payments have cleared, investigate disputes and chargebacks, store information in an accounting system and so on.

Payson can only make requests to the standard ports, meaning port 80 for http and 443 for https requests. If you specify another port the IPN call will fail.

Important: Please note that your ipnNotificationUrl may be called more than once from the Payson service for a given payment. Also note that IPN messages are sent for all status changes, even when a payment fails.

You must validate the IPN content and verify the payment status before marking the payment as done in your system.


Simple Integration

The quickest way to send a customer to the payment page is by posting a form to Payson will wrap your request and redirect the customer.There are several limitation to this way of calling our API.

  • No ipn will be sent
  • The invoice option it not available
  • Different test environment
  • Only one receiver

Please note that you must send the form by “POST”, not by “GET”. The form should be ISO-8859-1 encoded.

Form request parameters

RequiredParameterData typeDescription
OptionalRefNrstring (50)Your reference to the order. The RefNr is returned to the OkURL.
RequiredOkURLstring (255), html encodedUrl called when a payment is completed. The “return to shop” button will redirect the customer to OkURL.
RecommendedCancelURLstring (255), html encodedURL called when a payment failed or if the customer cancels the payment.
RequiredAgentIdintThe unique id provided by Payson when you have been approved as a merchant
RequiredMD5string (128)The MD5 needs to be calculated with your secret MD5 key prior to sending the request to Payson. The calculation is described below.
RequiredGuaranteeOfferedintSet to 1 if you do not want to offer PaysonGaranti and 2 to offer PaysonGaranti.
OptionalCustomReceiptstring(5)False if you want to use Payson’s receipt page. Please note that if you set CustomReceipt to True the customer will be sent to the OkURL immediately after the payment.
OptionalPaymentMethodstring(20)0 (zero) = Show all payment options (Card, internet bank, Payson)
1 = Card (VISA/MasterCard)
2 = Internet bank (SEB, Handelsbanken, Nordea, Danske bank and Swedbank)
All available payment options will be shown if left empty.
OptionalLocaleCodestring(2)Language used in the checkout window.
SV = swedish
EN = english
FI = finnish
Swedish will be the language used if left empty.

Receiver Details

RequiredParameterData typeDescription
RequiredSellerEmailstring (50)Email address of the receiver.

Buyer Details

RequiredParameterData typeDescription
OptionalBuyerEmailstring(128)The buyer’s email address.
OptionalBuyerFirstNamestring(70)The buyer’s first name.
OptionalBuyerLastNamestring(70)The buyer’s last name.

Product information

RequiredParameterData typeDescription
RequiredDescriptionstring(200)A description of the product or service bought. The description is shown in the confirmation email and in the Payson account.
RequiredCostdecimalThe price of the product or service. Must be more than 10 SEK or 1 EUR.
RequiredExtraCostdecimalUsed for additional charges such as shipping.
OptionalCurrencyCodeCurrencyCodeThe currency of the payment, SEK or EUR
Default: SEK

Calculating the MD5 hash

To confirm that a call to Payson has been made by the expected shop and that nothing has been added you need to calculate a MD5 hash.

String text = SellerEmail + “:” + Cost + “:” + ExtraCost + “:” + OkURL + “:” + GuaranteeOffered + Key

String Generated_MD5_Hash_Value = MD5(text)

Response to OkURL and CancelURL

If the payment is successful Payson makes up to two requests to OkURL; one from the servers and one if the user is redirected back to the shop by the CustomReceipt parameter or by pressing the “Return to shop” button. If the transaction was canceled or the payment failed a call will instead be made to CancelUrl.

The response will include:

  • OkURL – The address that the response is sent to
  • PaysonRef – The unique id of this transaction in Payson’s system
  • MD5 – MD5 hash to validate the call
  • RefNr – The reference used in your system, if set
  • Fee – The transaction fee

Validating response

Always validate the response to make sure that the call comes from Payson. The OkURL needs to be url decoded and html encoded before the calculation (automatic in $_REQUEST below)

$strYourSecretKey = "?????????";
$strOkURL = $_REQUEST["OkURL"];
$strPaysonRef = $_REQUEST["Paysonref"];
$strTestMD5String = htmlspecialchars( $strOkURL . $strPaysonRef ). $strYourSecretKey;
$strMD5Hash = md5($strTestMD5String);
if($strMD5Hash == $_REQUEST["MD5"]){
    //Correct call from Payson
    echo "Rätt MD5-summa";
} else {
    //Incorrect call, not from Payson
    echo "Felaktig MD5-summa";

Example Code

Functions for calculating the MD5 hash and examples in asp, asp .net and php may be found on

All required parameters must be included when sending the form to Payson, see example below. Note that there is no test server for simple integration. In order to test that your integration works, you must conduct a real payment and then credit the transaction. Remember that the smallest possible transaction amount is 10 SEK.

<form action="" method="post"> 
    <input type="hidden" name="BuyerEmail" value=""> 
    <input type="hidden" name="SellerEmail" value=""> 
    <input type="hidden" name="Description" value="En fin grej."> 
    <input type="hidden" name="Cost" value="100"> 
    <input type="hidden" name="ExtraCost" value="5,20">
    <input type="hidden" name="OkURL" value=""> 
    <input type="hidden" name="AgentId" value="000000"> 
    <input type="hidden" name="GuaranteeOffered" value="0">    
    <input type="hidden" name="MD5" value="Generated_MD5_Hash_Value"> 
    <input type="submit" value="Betala med Payson">


To validate your parameters, use instead of the production endpoint( ).

Images for website use