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

 

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.
OptionalfeesPayerFeesPayerThe payer of the Payson fees.
Default: PRIMARYRECEIVER
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 4 SEK or 0,4 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 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