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://checkout.payson.se/payment/?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