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.
Optional LocaleCode string(2) Language used in the checkout window.
SV = swedish
EN = english
FI = finnish
Swedish will be the language used if left empty.

Receiver Details

Required Parameter Data type Description
Required SellerEmail string (50) Email address of the receiver.

Buyer Details

Required Parameter Data type Description
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 Parameter Data type Description
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 or 0,4 EUR.
Required ExtraCost decimal Used for additional charges such as shipping.
Optional CurrencyCode CurrencyCode The 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 Agentintegration.zip.

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 4 SEK.

<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://account.payson.se/Utils/TestSimpleIntegrationParams instead of the production endpoint(https://www.payson.se/merchant/default.aspx ).

Images for website use