SDK

Libraries are hosted at GitHub.

PHP: https://github.com/PaysonAB/Payson1-PHP
This is a library for Payson 1.0.
Code examples for this library are included in the example folder.

.NET: https://github.com/PaysonAB/Payson1-.NET
The library include a complete demo store to get you started, visit code samples for examples using this library.

SEK – Invoice, Payment plan, Card (Visa, MasterCard), Direct payment by bank, PaysonAccount
EUR – Card (Visa, MasterCard), Direct payment by bank, PaysonAccount

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.

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

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.

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 TestAccount (on the test enironment) and see the requestlogs for your test agent.

Any credit card with a valid checksum digit and valid prefix will work for test transactions. The card will not be charged.

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

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.
• 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 https://test-www.payson.se and see all transactions and API requests there.
• Missing functionality. Not all functionality is available in the TestAccount 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.

HTTP Headers

Headers are used to specify API credentials and HTTP content type. The following HTTP Headers can/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’.

HTTP response

In all cases except for the ‘Validate’ 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.

Ensure that all API calls are made with TLS 1.1 or higher.

Payment Token

You will receive a payment reference, or ‘payment token’, from an initial pay action. The token will be used in most of subsequent requests to Payson regarding that payment.

Get details about an existing payment.

API method: POST

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

PaymentDetails request parameters

PaymentDetails Response Parameters

Shipping address

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.

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

• CANCELORDER – Cancel a payment before it is shipped.
  Note: Possible if type is INVOICE and invoiceStatus is ORDERCREATED.
• SHIPORDER – Mark an invoice payment as shipped (capture payment). The sender will be notified by Payson that an invoice has been created.
  Note: Possible if type is INVOICE and invoiceStatus is ORDERCREATED.
• CREDITORDER – Credit an invoice payment.
  Note: If the receiver account has insufficient funds it is not possible to credit the order. Possible if type is INVOICE and invoiceStatus is SHIPPED or DONE.
• REFUND – Refunds a bank or card payment to the sender. If the sender deposited the amount it will be refunded to the origin 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: Possible if type is TRANSFER.
• CANCELPAYMENT – Cancels a pending bank or card payment.
  Note: Possible if type is TRANSFER.

API method: POST

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

PaymentUpdate request parameters

PaymentUpdate Response Parameters

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

API method: POST

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

Validate request parameters

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

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. For instance, confirm that the payment status is COMPLETED for bank and card payments and Payson Guarantee payments. For invoice payment, make sure the invoiceStatus is ORDERCREATED. You should also 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.

This method is used to validate API credentials and get basic information about API account.

API method: POST

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

AccountInfo request parameters

No additional parameters should be sent.
For some curl requests it might be necessary to set ‘Content-Length: 0’ in header.

AccountInfo Response Parameters

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:

• [Deprecated] OPTIONAL
• [Deprecated] REQUIRED
• NO

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
• DK
• NO

AckCode

• SUCCESS
• FAILURE

PaymentType

• TRANSFER – This is a bank or card payment.
• [Deprecated] GUARANTEE – This is a Payson Guarantee payment.
• INVOICE – This is an invoice payment.

PaymentStatus

Note: for invoice and Guarantee payments the corresponding statuses (InvoiceStatus and GuaranteeStatus) should be used.

• 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.
• ERROR – The payment failed and all attempted transfers failed or all completed transfers were successfully reversed.
• ABORTED – The payment was aborted before any money were transferred.

[Deprecated] GuaranteeStatus

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

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

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 and a hash parameter. It will not include 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.

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

Receiver Details

Buyer Details

Product information

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 10 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