Payson Integration Guide

API endpoint

Forward endpoint

Revision History

Getting started

In order to use Paysons API, you first need API credentials. These can be applied for at your Payson Account by clicking on 'My Account' and then clicking on 'Integration'. Once you have been approved by Payson, you can see your credentials at the very same page where you applied for them. These credentials must be provided in each request to Payson.

Security

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

Payson API structure

The Payson API uses a client-server model in which your site is a client of a Payson API server.

Actions are initiated by sending an HTTP POST request to one of Paysons endpoint URIs. Each action has its own parameters which must be included in each request, so be sure to set them up properly.
The response from the Payson server contain information about the overall success of the request and possible additional data depending on which action that was requested.

The following diagram shows the basic request-response mechanism:

HTTP POST request structure

Each request to Payson must be properly set up with the specific parameters required for the requested action. If a required parameter is not included, the requested action will not be taken. The same goes for incorrectly formatted parameters. Please be sure to look at the specification for each parameter before making a request to an endpoint URI.

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:

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'.
Each action has its own set of required parameters, please see the specification for each action below for more information on those parameters.

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. Please see the specification for each action for more information about which parameters are included.

Multiple successive API Actions

Most of the features you may want to implement requires multiple successive API actions per payment. Features such as completing a payment on your site or shipping an invoice require more than one API action per payment. Typically, you will receive a payment reference (or 'token') from the initial action requested. The reference must be used in all subsequent requests to Payson regarding that payment. A typical example of this would be:

1. Make a 'Pay' request, that initializes a payment at Payson and gives you a reference to be included in the URI to which the customer is redirected.
2. When the customer returns to your site, make a request to 'PaymentDetails' using the reference from the previous request and check the status of the payment to ensure the payment was completed.

The following diagram shows the scenario described above:

Actions

An action is a remote procedure call on Paysons servers. As described in previous sections, actions are initiated by sending HTTP POST requests to endpoint URIs located at Paysons servers.
Each action has a set of parameters that may be included in the request to control the details of the action. Some of these parameters are required and if one of them is missing, no action will be taken. Other parameters are optional and may be included if desired. Some the optional parameters have default values that will be set if the parameters are not included in the request; be sure to check out the specification for these parameters to avoid undesired behavior when the customer redirected to Payson.

In this section all possible actions will be explained and all parameters will be specified. Available actions are:

• Initialize payment
• Look up payment details
• Update payment
• Validate IPN callback

Initialize payment

This is the starting point for any kind of payment. The parameters included in a request completely determines what kind payment options are available to the customer as well as a number of other options.
In the listing below, all required parameters are marked as such. These parameters must always be provided for a successful API request.

Invoice payments

Please note that for invoice payments, a further set of parameters become required. Please read the entire specification for information on which parameters are required for invoice payments.
Also, please note that a separate agreement is required to start receiving payments by invoice and that at the moment the only supported currency is SEK. Follow this link for more information.

Fees

You can set up a payment so that either the sender or one of a payment pays the fee or the receivers of a payment pay the fee. If receivers pay the fee, you can specify whether the primary receiver in a chained payment pays the entire fee or whether all receivers pay their portion of the fee. Fees are determined by Payson and are based on criteria, such as the transaction volume of the receiver. You can specify who pays these fees.

• Sender pays the fee
• Primary receiver pays the fee

Response

If a request is successful, a reference token is returned which must be used in all subsequent API requests regarding the payment. The token must also be used when forwarding the user to Payson for completion of payment. A list of returned parameters can be found here »
If a request is not successful, a message containing an error code and a possible explanation of the error is provided. More information on error codes can be found here »

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

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

Pay Response Parameters

PaymentDetails request

Get details about a existing payment.

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

PaymentDetails Response Parameters

PaymentUpdate request

Update an existing payment, for instance mark an order as shipped or canceled.

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

PaymentUpdate Response Parameters

Introducing IPN

Instant Payment Notification (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

When the payment is complete, an IPN message is sent to the URL specified in the ipnNotificationUrl field of the Pay request. In the case of a Payson invoice payment, the IPN message is sent when the order is created.

An IPN message consists of the same NVP formatted content as a request to PaymentDetails will give except for the response envelope parameters.

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 when a payment fails. You must verify the payment status before marking the payment as done in your system.

Validate request

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 Response Parameters

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.

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.

Error Codes

Error Response Parameters

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

Error Codes

Code examples

This section suggests possible implementations for communicating with the Payson API in C# and PHP. The examples make use of libraries implemented by Payson, which can be found at github (C#, PHP). The libraries have similar class structures, so in the following discussion only the C# library structure will be discussed. The examples will however be shown in both C# and PHP.

All classes in the library are placed in the top-level namespace PaysonIntegration. In the following examples, namespaces are excluded for brevity. 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);
                    

If you have received an application ID from Payson, you can enter it in the constructor as well as a third argument. Please note that the application ID is not part of a normal usage of the Payson API. If you have not been given an application ID by Payson, then ignore this parameter.

PaysonApi paysonApi = new PaysonApi("your_user_id", "your_user_key", 
                                    "your_application_id");
                    

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

The paysonApi object contains methods for making requests to most API endpoints. Each method takes as input an object containing all parameters needed to complete the request, and returns a response object containing the parsed results of the request for your convenience. All input and response classes can be found in the namespaces PaysonIntegration.Data and PaysonIntegration.Response respectively.

The general structure of input objects is that 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.

If none of the methods of the paysonApi object fills your need, you can write your own extensions by using the HttpCaller class. Please refer to the source code of the PaysonApi class on how to use the HttpCaller class.

Initializing payments

To initialize a payment you use the Pay API endpoint. The procedure is pretty much the same for any payment type. You set up an object of class PayData with the parameters needed for the payment type, then make a Pay request using an object of class PaysonApi. The response object will contain the information you need to redirect your customer to Payson to complete the payment.

Payson Direct

Here is how you could 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.SetFirstName("sender_first_name");
paymentSender.SetLastName("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.SetFirstName("sender_first_name");
paymentSender.SetLastName("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 info

To get details about a payment, you send a request to the PaymentDetails API endpoint. For such a request you need to provide the token received from a previously successful request to the Pay API endpoint which initiated the payment. The following code shows how you can use the libraries to make the request:

var paymentDetailsData = new PaymentDetailsData(payResponse.Token);
var paymentDetailsResponse = payApi.MakePaymentDetailsRequest(paymentDetailsData);
                    

$paymentDetailsData = new PaymentDetailsData($payResponse->getToken());
$paymentDetailsResponse = $api->paymentDetails($paymentDetailsData);
                    

You can then use the paymentDetailsResponse.PaymentDetails object to, for instance, find out 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, then Payson will send an IPN message to that URL when the payment has been initialized/finished at Payson. 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
}
                    

$content = "the_content_from_the_http_request_to_your_ipn_url";
$validateResponse =  $api->validate($content);
if ($validateResponse->isVerified()){
   // IPN was confirmed by Payson
}
                    

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

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 integration with the banks are available and 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):

1

API Password (MD5-key):

fddb19ac-7470-42b6-a91d-072cb1495f0a

Receiver Email:

testagent-1@payson.se

Important: The above 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).

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 check sum 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

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. A 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. 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.
• 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 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.