Payson


Payson Integration Guide

Version 1.22
Last updated: 2014-09-11

API endpoint

https://api.payson.se

Forward endpoint

https://www.payson.se/paysecure/


Getting started

Apply for credentials by logging in to your Payson Account by clicking 'My Account' -> 'Integration'. Once you have been approved by Payson, you will be notified by email and your credentials will show on the Integration page.

Invoice payments

A separate agreement is required to start receiving payments by invoice and at the moment the only supported currency is SEK. The receiver of the payment has to be the same Payson account as the account used for the request, e.g. the email address associated with the Payson account for the PAYSON-SECURITY-USERID used in the HTTP header. Follow this link for more information.

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 POST request structure

HTTP Headers

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

Required Header Description
Required PAYSON-SECURITY-USERID Your API User ID (AgentId).
Required PAYSON-SECURITY-PASSWORD Your API Password (MD5-key).
Required Content-Type Value must be: application/x-www-form-urlencoded
Optional PAYSON-APPLICATION-ID Your 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 'Verify' 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:

https://www.payson.se/paySecure/?token={token}

Security

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

Payment Token

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

Execution flow between your site and Payson

Payment page

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.

Payment page with all payment methods visible

Payment page with all available payment methods visible. A Payson account button will be added as well if there is an active Payson account registered for SenderEmail.



Payment page once the Invoice option has been selected

Payment page with the invoice option selected.



Payment page with a payson account and constraint CREDITCARD

Appearance when the pay request was sent with FundingConstraint=CREDITCARD and the senderEmail has an active Payson account already.



Payment page with all payment methods visible

The payment page on a tablet.



Actions

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

Available actions are:

Pay action

Initializes a payment request

API endpoint: https://api.payson.se/1.0/Pay/

Pay request parameters


Required Parameter Data type Description
Required returnUrl string (2048) URL to which the customer's browser is redirected after the payment is completed.

Note: This includes both successful and unsuccessful payments.

Required cancelUrl string (2048) URL to which the customer is redirected if the payment is manually canceled by the user before it is completed.
Recommended ipnNotificationUrl string (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 »

Required memo string (128) Description of items the customer is purchasing.
Required senderEmail string (128) Email address of the person sending money. This is the Payson account where the settled amount is transferred from.
Required senderFirstName string (128) First name of the buyer as entered during checkout.
Required senderLastName string (128) Last name of the buyer as entered during checkout.
Optional localeCode LocaleCode Locale of pages displayed by Payson during payment.
Default: SE
Optional currencyCode CurrencyCode The currency used for the payment.
Default: SEK
Optional fundingList.fundingConstraint (0..N).constraint FundingConstraint Specifies 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).
Optional feesPayer FeesPayer The payer of the Payson fees.
Default: PRIMARYRECEIVER
Optional invoiceFee decimal An invoice fee that will be added as an order item.
  • Must be in the range 0 to 40
Optional custom string (256) A free-form field for your own use. This will be returned in requests to the PaymentDetails API endpoint.
Optional trackingId string (128) Your own tracking id. This will be returned in requests to the PaymentDetails API endpoint.
Optional guaranteeOffered GuaranteeOffered Whether Payson Guarantee is offered or not.
Default: OPTIONAL
Optional showReceiptPage bool Whether to show the receipt page in Paysons checkout. Default: true

Receiver Details

The list of receivers. If you have more than one receiver you must specify exactly one as primary.
Required receiverList.receiver (0..N).email string (128) Email address of the receiver.
Required receiverList.receiver (0..N).amount decimal The amount (including VAT) to transfer to this recipient.
Optional receiverList.receiver (0..N).primary bool Whether 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.
For each orderItem, you must specify all or none of the parameters sku, quantity, unitPrice & taxPercentage.
Required orderItemList.orderItem (0..N).description string (128) Description of this item.
Optional orderItemList.orderItem (0..N).sku string (128) SKU of this item.(E.g. "kg", "st")
Optional orderItemList.orderItem (0..N).quantity decimal Quantity of this item.
Optional orderItemList.orderItem (0..N).unitPrice decimal The unit price of this item not including VAT.
Optional orderItemList.orderItem (0..N).taxPercentage decimal Tax 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

Parameter Data type Description
responseEnvelope.ack AckCode Acknowledge code indicating the overall success of the request.
responseEnvelope.timestamp DateTime Timestamp that identifies when the response was sent.
TOKEN Guid A token by which you identify to Payson that you are processing this payment.

PaymentDetails action

Get details about an existing payment.

API endpoint: https://api.payson.se/1.0/PaymentDetails/

PaymentDetails request parameters

Required Parameter Data type Description
Required token Guid The token obtained when creating the payment.

PaymentDetails Response Parameters

Parameter Data type Description
responseEnvelope.ack AckCode Acknowledge code indicating the overall success of the request.
responseEnvelope.timestamp DateTime Timestamp that identifies when the response was sent.
purchaseId int Payson purchaseId for this payment.
senderEmail string The sender's email address.
status PaymentStatus The status of the payment.
type PaymentType Type of payment.
guaranteeStatus GuaranteeStatus The status of an ongoing Payson Guarantee payment. This is only set if type is GUARANTEE.
guaranteeDeadlineTimestamp DateTime Timestamp that identifies when the next guarantee deadline is due, if one exists.
invoiceStatus InvoiceStatus The status of an ongoing Payson Invoice payment. This is only set if type is INVOICE.
custom string A free-form field submitted with the Pay request.
trackingId string Your own invoice or tracking id submitted with the Pay request.
receiverList.receiver(n).email string Email address of the receiver.
receiverList.receiver(n).amount string The amount to transfer to this receiver.
receiverList.receiver(n).primary bool Determines whether this is the primary receiver or not.
currencyCode CurrencyCode A three-character currency code.
receiverFee decimal The fee charged the receiver of the payment

Shipping address

Invoice 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.
shippingAddress.name string The name of the shipment's receiver.
shippingAddress.streetAddress string The shipment receiver's street address.
shippingAddress.postalCode string The shipment receiver's postal code.
shippingAddress.city string The shipment receiver's city.
shippingAddress.country string The shipment receiver's country.

PaymentUpdate action

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

  • CANCELORDER - Cancel an order before it is shipped and thereby canceling the entire payment.
    Note: Only possible if type is INVOICE and invoiceStatus is ORDERCREATED.
  • SHIPORDER - Ship an order and thereby convert it into an invoice. The sender will be notified by Payson that an invoice has been created.
    Note: Only possible if type is INVOICE and invoiceStatus is ORDERCREATED.
  • CREDITORDER - Credit an order that has been shipped. A credit invoice will be issued for the entire invoice.
    Note: The full amount including Payson's fee will be drawn from the receiver account. If the receiver account has insufficient funds it is not possible to credit the order. If Payson has not yet settled money to the receiver, the fee will still be drawn from the account. Only possible if type is INVOICE and invoiceStatus is SHIPPED or DONE.
  • REFUND - Refunds a Payson Direct payment to the sender. If the sender deposited the amount it will be refunded to the origin (credit card/bank) 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: Only possible if type is DIRECT.
  • CANCELPAYMENT - Cancels a pending Payson Direct payment, meaning the associated token can not be used to complete the payment.

API endpoint: https://api.payson.se/1.0/PaymentUpdate/

PaymentUpdate request parameters

Required Parameter Data type Description
Required token Guid The token obtained when creating the payment.
Required action UpdateAction Action to take for this payment.

PaymentUpdate Response Parameters

Parameter Data type Description
responseEnvelope.ack AckCode Acknowledge code indicating the overall success of the request.
responseEnvelope.timestamp DateTime Timestamp that identifies when the response was sent.

Validate action

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

API endpoint: https://api.payson.se/1.0/Validate/

Validate request parameters

Parameter Description
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

Description
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

Important:
After you receive the VERIFIED message, there are other important checks you should perform before you can assume that the message is legitimate. For instance, confirm that the payment status is COMPLETED for Payson Direct and Payson Guarantee payments. For Payson Invoice payment, make sure the invoiceStatus is ORDERCREATED. You could also use the trackingId to 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.

Instant Payment Notification (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 except for the response envelope parameters.

Restrictions
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
  • verify the payment status
before marking the payment as done in your system.

Data types

Decimal

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

Guid

A 38 characters long globally unique identifier.

GuaranteeOffered

Must be one of the following values:

  • OPTIONAL
  • REQUIRED
  • NO

FeesPayer

Must be one of the following values:

  • SENDER
  • PRIMARYRECEIVER

FundingConstraint

Must each be one of the following values:

  • CREDITCARD
  • BANK
  • INVOICE

CurrencyCode

Must be one of the following values:

  • SEK
  • EUR

LocaleCode

Must be one of the following values:

  • SV
  • EN
  • FI

AckCode

One of the following values:

  • SUCCESS
  • FAILURE

PaymentStatus

Please note that for Invoice and Guarantee payments the corresponding statuses (InvoiceStatus and GuaranteeStatus) should be prioritized. Can be one of the following values:

  • 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. Some transfers succeeded and some failed for a parallel payment.
  • 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.

PaymentType

Can be one of the following values:

  • TRANSFER - This payment is a Payson Direct payment.
  • GUARANTEE - This is a Payson Guarantee payment.
  • INVOICE - This is a Payson Invoice payment.

GuaranteeStatus

It can be one of the following values:

  • WAITINGFORSEND
  • WAITINGFORACCEPTANCE
  • WAITINGFORRETURN
  • WAITINGFORRETURNACCEPTANCE
  • RETURNNOTACCEPTED
  • NOTRECEIVED
  • RETURNNOTRECEIVED
  • MONEYRETURNEDTOSENDER
  • RETURNACCEPTED

InvoiceStatus

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.

UpdateAction

Must be one of the following values:

  • CANCELORDER
  • SHIPORDER
  • CREDITORDER
  • REFUND
  • CANCELPAYMENT

Error Codes

Error Response Parameters

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

Parameter Description
errorList.error(n).errorId A number that uniquely identifies an error.
errorList.error(n).message A description of errorId.
errorList.error(n).parameter Indicates which submitted parameter caused the error. Only included where appropriate.

Error Codes

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

Code examples

The examples make use of libraries implemented by Payson, which can be found at github (C#, PHP).

To start making requests, you create an object of type PaysonApi where you provide your credentials as constructor arguments.

PaysonApi paysonApi = new PaysonApi("your_user_id", "your_user_key");
                    
$credentials = new PaysonCredentials("your_user_id", "your_user_key");
$api = new PaysonApi($credentials);
                    

The paysonApi object contains methods for making requests to Paysons API endpoints. All input and response classes can be found in the namespaces PaysonIntegration.Data and PaysonIntegration.Response respectively.

You initialize the object with the required parameters as constructor arguments, then set optional parameters using set methods. Additional classes for managing input/output for the requests can be found in the namespace PaysonIntegration.Utils.

Initializing payments

To initialize a payment you create an object of type PayData with the parameters needed for the payment type, then invoke MakeyPayRequest on PaysonApi.

If the call is successful, the response object will contain the payment token. This token is your unique handle for this payment request at Payson. You need this token to redirect your customer to Payson to complete the payment.

If the call is not successful, we will respond with a list of error messages. See Error Codes.

Payson Direct

Example of how to use the libraries to initiate a Payson Direct payment of 100 SEK and then redirect the customer to Payson:

var paymentSender = new Sender("sender_email");
paymentSender.FirstName = "sender_first_name";
paymentSender.LastName = "sender_last_name";
var receivers = new List<Receiver>{ new Receiver("receiver_email", 100m) };
var payData = new PayData("return_url", "cancel_url", "description",
                          paymentSender, receivers);
 
payData.SetIpnNotificationUrl("ipn_notification_url");
payData.SetCurrencyCode("SEK");
payData.FeesPayer = FeesPayer.Sender;
 
PayResponse payResponse = paysonApi.MakePayRequest(payData);
 
if(payResponse.Success)
{
    Response.Redirect(paysonApi.GetForwardPayUrl(payResponse.Token));
}
                    
$sender = new Sender("sender_email", "sender_first_name", "sender_last_name");
$receivers = array(new Receiver("receiver_email", 100));
 
$payData = new PayData("return_url", "cancel_url", "ipn_url",
                       "description", $sender, $receivers);
 
$payResponse = $api->pay($payData);
 
if ($payResponse->getResponseEnvelope()->wasSuccessful())
{
    header("Location: " . $api->getForwardPayUrl($payResponse)); /* Redirect */
}
                    

FeesPayer is an enum that can be found in PaysonIntegration.Utils, along with other enums and helper classes used in various situations.

Payson Invoice

To initiate a Payson Invoice payment of 250 SEK (Including VAT) with an invoice fee of 20 SEK (i.e. a total of 270 SEK) and then redirect the customer to Payson, you could use the following code:

var paymentSender = new Sender("sender_email");
paymentSender.FirstName = "sender_first_name";
paymentSender.LastName = "sender_last_name";
var receivers = new List <Receiver> { new Receiver("receiver_email", 270m) };
var payData = new PayData("return_url", "cancel_url", "description",
                          paymentSender, receivers);
payData.SetIpnNotificationUrl("ipn_notification_url");
payData.SetCurrencyCode("SEK");
payData.FeesPayer = FeesPayer.PrimaryReceiver;
var orderItems = new List<OrderItem>();
var orderItem = new OrderItem("Book collection");
orderItem.SetOptionalParameters("001", 1m, 200m, 0.25m);
orderItems.Add(orderItem);
payData.SetOrderItems(orderItems);
payData.SetInvoiceFee(20m);
var fundingList = new List<FundingConstraint> { FundingConstraint.Invoice };
payData.SetFundingConstraints(fundingList);
 
PayResponse payResponse = paysonApi.MakePayRequest(payData);
 
if(payResponse.Success)
{
    Response.Redirect(paysonApi.GetForwardPayUrl(payResponse.Token));
}
                    
$sender = new Sender("sender_email", "sender_first_name", "sender_last_name");
$receivers = array(new Receiver("receiver_email", 270));
 
$constraints = array(FundingConstraint::INVOICE);
$orderItems = array(new OrderItem("Book collection", 200, 1, 0.25, "001"));
 
$payData = new PayData("return_url", "cancel_url", "ipn_url",
                       "description", $sender, $receivers);
 
$payData->setFeesPayer("PRIMARYRECEIVER");
$payData->setFundingConstraints($constraints);
$payData->setOrderItems($orderItems);
$payData->setCurrencyCode("SEK");
$payData->setInvoiceFee(20);
 
$payResponse = $api->pay($payData);
 
if ($payResponse->getResponseEnvelope()->wasSuccessful())
{
    header("Location: " . $api->getForwardPayUrl($payResponse)); /* Redirect */
}
                    

FundingConstraint is an enum that can be found in PaysonIntegration.Utils.

Payment details

To get details about a payment you invoke MakePaymentDetailsRequest on PaysonApi with the payment token as parameter.

var paymentDetailsData = new PaymentDetailsData(payResponse.Token);
var paymentDetailsResponse = payApi.MakePaymentDetailsRequest(paymentDetailsData);
                    
$paymentDetailsData = new PaymentDetailsData($payResponse->getToken());
$paymentDetailsResponse = $api->paymentDetails($paymentDetailsData);
                    

Use the paymentDetailsResponse.PaymentDetails object to, for instance, get the state of the payment or the shipping address of the invoice customer.

Changing the state of a payment

To update a payment you make a request to the PaymentUpdate API endpoint. The request must contain the token received from a previously successful request to the Pay API endpoint as well as an action to be taken for the payment. For instance, to ship an order - and thereby issue an invoice - you could use the following code:

var paymentUpdateData = new PaymentUpdateData(
                                payResponse.token,
                                PaymentUpdateAction.ShipOrder);
var paymentUpdateResponse = paysonApi.MakePaymentUpdateRequest(paymentUpdateData);
                    
$paymentUpdateData = new PaymentUpdateData(
                            $payResponse->getToken(),
                            PaymentUpdateMethod::ShipOrder);
$paymentUpdateResponse = $api->paymentUpdate($paymentUpdateData);
                    

PaymentUpdateAction is an enum that can be found in PaysonIntegration.Utils.

Validating an IPN request

If you have specified an IPN callback URL in your request to the Pay API endpoint, Payson will send an IPN message to that URL when the payment changes its state. You need to validate this message to be sure it originated from Payson by sending the content of the IPN message in an unprocessed form back to Payson. For this you should use the Validate API endpoint. The following code shows how such a procedure could be made:

string content = "the_content_from_the_http_request_to_your_ipn_url";
var validateResponse = paysonApi.MakeValidateIpnContentRequest(content);
if (validateResponse.Success) {
    // IPN was confirmed by Payson
    // Here you would check the status of the payment and update your system accordingly
}
                    
$content = "the_content_from_the_http_request_to_your_ipn_url";
$validateResponse =  $api->validate($content);
if ($validateResponse->isVerified()){
   // IPN was confirmed by Payson
   // Here you would check the status of the payment and update your system accordingly
}
                    

If the property validateResponse.Success is true, then Payson has confirmed the request. You can use the validateResponse.ProcessedIpnMessage to conveniently access data from the IPN message content.

Testing / sandbox

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 OK or denied bank response.

A fully working demo shop using the test system is online at DemoShop

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
Receiver Email:
testagent-1@payson.se

Important: The test credentials can only be used when initiating a test transaction i.e. when communicating with test-api.payson.se and test-www.payson.se. 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 test account (on the test enironment) and see the requestlogs for your test agent.

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

Customer Email:
test-shopper@payson.se

Test Credit Card

Any card with a a valid checksum digit and valid prefix will work. In case you do not have a card available a generated card is specified below.

Card number:
4581 1111 1111 1112
Expiration Date:
Any
Cvc:
Any
Method/Action Test URL
Pay Forward URL https://test-www.payson.se/paysecure/?token={token}
Pay Endpoint https://test-api.payson.se/1.0/Pay/
PaymentDetails Endpoint https://test-api.payson.se/1.0/PaymentDetails/
PaymentUpdate Endpoint https://test-api.payson.se/1.0/PaymentUpdate/
Validate Endpoint https://test-api.payson.se/1.0/Validate/

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.
  • Only one IPN is sent. An IPN will be sent for payments. However, unlike the live system you will not receive updated IPN calls at a later time.
  • 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 test-www.payson.se and see all transactions and API requests there.
  • Missing functionality. Not all functionality is available on the actual Payson site (https://test-www.payson.se)

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.

Checklist before going live

Please make sure you follow these steps before going live with your Payson integration.

  1. Make sure the IPN message is sent from Payson by calling the Validate API on your handler for the ipnNotificationUrl .
  2. Make sure that the status parameter is COMPLETED before you mark an order as paid on your ipnNotificationUrl page.
  3. Always check the status of the payment on returnUrl page by calling PaymentDetails API.
  4. Please note that your ipnNotificationUrl may be called more than once from the Payson service.

Simple integration (no ipn)

The quickest way to send a customer to the payment page is by posting a form to https://www.payson.se/merchant/default.aspx. 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


Required Parameter Data type Description
Optional RefNr string (50) Your reference to the order. The RefNr is returned to the OkURL.
Required OkURL string (255), html encoded Url called when a payment is completed. The "return to shop" button will redirect the customer to OkURL.
Recommended CancelURL string (255), html encoded URL called when a payment failed or if the customer cancels the payment.
Required AgentId int The unique id provided by Payson when you have been approved as a merchant
Required MD5 string (128) The MD5 needs to be calculated with your secret MD5 key prior to sending the request to Payson. The calculation is described below.
Required GuaranteeOffered int Set to 1 if you do not want to offer PaysonGaranti and 2 to offer PaysonGaranti.
Optional CustomReceipt string(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.
Optional feesPayer FeesPayer The payer of the Payson fees.
Default: PRIMARYRECEIVER
Optional PaymentMethod string(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.

Receiver Details

Required SellerEmail string (50) Email address of the receiver.

Buyer Details

Optional BuyerEmail string(128) The buyer's email address.
Optional BuyerFirstName string(70) The buyer's first name.
Optional BuyerLastName string(70) The buyer's last name.

Product information

Required Description string(200) A description of the product or service bought. The description is shown in the confirmation email and in the Payson account.
Required Cost decimal The price of the product or service. Must be more than 4 SEK.
Required ExtraCost decimal Used for additional charges such as shipping.

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 https://www.payson.se/Info/Agentintegration/.

All required parameters must be included when sending the form to Payson, see example below.

<form action="https://www.payson.se/merchant/default.aspx" method="post"> 
    <input type="hidden" name="BuyerEmail" value="buyer@mymail.com"> 
    <input type="hidden" name="SellerEmail" value="seller@mymail.com"> 
    <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="http://www.myokurl.com"> 
    <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">
</form>                  

Testing

To validate your parameters, use https://www.payson.se/testagent/default.aspx instead of the production endpoint(https://www.payson.se/merchant/default.aspx ).

Images for website use

Revision History

Date Version Description
2014-09-11 1.22 Added screenshots and made some corrections and clarifications
2014-06-09 1.21 Added "quick integration"-option
2014-05-20 1.20 Reconstruction of the documentation.
2014-05-19 1.19 Made the text simpler. Clarified chained payments and updated some request and parameter info. Included test agent info.
2013-12-10 1.18 Added support for "ShowReceiptPage" which if 'false' will not show the receipt page in checkout. Default is 'true'.
2013-10-24 1.17 Clarification about returnUrl, cancelUrl and ipnNotificationUrl in Initialize payment
2013-10-14 1.16 PaymentUpdate method extended with ability to cancel a pending payment
2013-05-14 1.15 Added information about receiverFee in PaymentDetails