Payson


Payson Integration Guide

Version 1.18
Last updated: 2013-12-10

API endpoint

https://api.payson.se

Forward endpoint

https://www.payson.se/paysecure/


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.

API overview

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:

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:

Required Header Description
X PAYSON-SECURITY-USERID Your API User ID (AgendId).
X PAYSON-SECURITY-PASSWORD Your API Password (MD5-key).
PAYSON-APPLICATION-ID Your Application ID. (Only applicable if you have received one)
X Content-Type Value must be: application/x-www-form-urlencoded

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:

Execution flow between your site and Payson

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:

Pay request

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

Fee payment configurations include:
  • 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}

Parameter Description
returnUrl (Required) URL to which the customer's browser is redirected after the payment is completed.

Note: This includes both successful and unsuccessful payments.

Restrictions
Max 2048 characters.

cancelUrl (Required) URL to which the customer is redirected if the payment is manually canceled by the user before it is completed.

Restrictions
Max 2048 characters.

memo (Required) Description of items the customer is purchasing.

Restrictions
Max 128 alphanumeric characters.

ipnNotificationUrl (Optional) The URL for receiving an Instant Payment Notification about this payment.

Note: This parameter has been made optional due to backward compatability. We highly recommend implementing it. Read more about the use of it here »

Restrictions
Max 2048 characters.
Must use port 80 or 443 (the standard http and https ports)

localeCode (Optional) Locale of pages displayed by Payson during payment.

Restrictions
Two-character language codes (ISO 639-1).

The following language codes are currently supported by Payson:

  • SV - Swedish (default)
  • EN - English
  • FI - Finnish
currencyCode (Optional) The currency used for the payment.

Restrictions
Three-character currency codes (ISO 4217).

Currently supported currencies:

  • SEK - Swedish krona (default)
  • EUR - Euro
fundingList.fundingConstraint(0..N).constraint (Optional) Specifies a list of allowed funding selections for the payment. This is a list of funding selections that can be combined in any order to allow payments to use the indicated funding type. If this field is omitted, the payment can be funded by any funding type that is supported for the merchant (excluding invoice).

IMPORTANT: The INVOICE constraint must not be combined with any other constraint.

Restrictions
Must be one of the following values:

  • CREDITCARD
  • BANK
  • INVOICE
feesPayer (Optional) The payer of Payson fees.

This parameter is ignored if Payson guarantee is offered (guaranteeOffered is set to REQUIRED). If guarantee is used the buyer/sender will pay the fee.

Restrictions
Must be one of the following values:

  • SENDER - Sender pays all fees
  • PRIMARYRECEIVER - Primary receiver pays all fees (default)
invoiceFee (Optional) An invoice fee that will be added as an order item.

Restrictions

  • Must be in the range 0 to 40 SEK
  • Can have at most have two decimal places. E.g. These are ok: 10, 10.0, 10.00; but not these: 10.000, 10.00000
  • No currency symbol
  • Decimal separator must be a period (.). E.g. 10.00, NOT 10,00
custom (Optional) A free-form field for your own use. This will be returned in requests to the PaymentDetails API endpoint.

Restrictions
Max 256 alphanumeric characters.

trackingId (Optional) Your own invoice or tracking id. This will be returned in requests to the PaymentDetails API endpoint.

Restrictions
Max 128 alphanumeric characters.

guaranteeOffered (Optional) Whether Payson Guarantee is offered or not.

Restrictions
Must be one of the following values:

  • OPTIONAL - (default)
  • REQUIRED
  • NO
showReceiptPage (Optional) Whether to show the receipt page in Paysons checkout.

Restrictions
Must be one of the following values:

  • true - (default)
  • false

Sender Details

senderEmail (Required) Email address of the person sending money. This is the Payson account where the settled amount is transferred from.

Restrictions
Max 128 alphanumeric characters.

senderFirstName (Required) First name of the buyer as entered during checkout. Payson uses this value to pre fill the Payson membership signup portion of the Payson login page.

Restrictions
Max 128 alphanumeric characters.

senderLastName (Required) Last name of the buyer as entered during checkout. Payson uses this value to pre-fill the Payson membership signup portion of the Payson login page.

Restrictions
Max 128 alphanumeric characters.

Receiver Details

Use index number if more than one recipient is necessary.
receiverList.receiver(0..N).email (Required) Email address of the receiver.

Restrictions
Max 128 alphanumeric characters.

receiverList.receiver(0..N).amount (Required) The amount (including VAT) to transfer to this recipient.

Restrictions

  • Must not exceed $10,000 USD in any currency.
  • No currency symbol.
  • Can have at most have two decimal places. E.g. These are ok: 10, 10.0, 10.00; but not these: 10.000, 10.00000
  • Decimal separator must be a period (.). E.g. 10.00, NOT 10,00
receiverList.receiver(0..N).primary (Optional) Whether this receiver is the primary receiver.

Restrictions
Must be one of the following values:

  • true – primary receiver
  • false – secondary receiver
Note: You can specify at most one primary receiver and it applies only to chained payments. Please do not include this parameter in a simple payment.
receiverList.receiver(0..N).firstName (Optional) Firstname of receiver.

Restrictions
Max 50 alphanumeric characters.

receiverList.receiver(0..N).lastName (Optional) Lastname of receiver.

Restrictions
Max 50 alphanumeric characters.

Order Item Details

Note: Order Items are required for INVOICE payments and optional for other payment types. Also, please note that the total sum of all order items amount (inc. VAT) must match the total sum of all receivers amount.
orderItemList.orderItem(0..N).description (Required) Description of this item.

Restrictions
Max 128 alphanumeric characters.

Note: The following four parameters are all required if any of them are provided.
orderItemList.orderItem(0..N).sku SKU of this item.

Restrictions
Max 128 alphanumeric characters.

orderItemList.orderItem(0..N).quantity Quantity of this item.

Restrictions

  • Can have at most have two decimal places. E.g. these are ok: 10, 10.0, 10.00; but not these: 10.000, 10.00000
  • Decimal separator must be a period (.). E.g. 10.00, NOT 10,00
  • Do not use thousands separators. E.g. use 1000000 instead of 1,000,000 or 1 000 000
orderItemList.orderItem(0..N).unitPrice The unit price of this item not including VAT.

Restrictions

  • No currency symbol.
  • Can have at most have four decimal places. E.g. these are ok: 10, 10.0, 10.00, 10.0000; but not this: 10.00000
  • Decimal separator must be a period (.). E.g. 10.00, NOT 10,00
orderItemList.orderItem(0..N).taxPercentage Tax percentage for this item.

Restrictions

  • Must be a decimal value and not an actual percentage. E.g. for a 25% tax percentage use 0.25.
  • Can have at most six decimal places. E.g. these are ok: 0.25, 0.025, 0.0025; but not these: 0.2500000
  • Decimal separator must be a period (.).

Pay Response Parameters

Parameter Description
responseEnvelope.ack Acknowledge code indicating the overall success of the request. Can be one of the following values:
  • SUCCESS – Operation completed successfully.
  • FAILURE – Operation failed.
responseEnvelope.timestamp Timestamp that identifies when the response was sent.
responseEnvelope.correlatonId Correlation ID. Used only by Payson Technical Support. This is only returned if your request passes initial validation.
TOKEN A token by which you identify to Payson that you are processing this payment.

PaymentDetails request

Get details about a existing payment.

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

Parameter Description
token (Required) The token obtained when creating the payment.

Restrictions
GUID, 38 characters.

PaymentDetails Response Parameters

Parameter Description
responseEnvelope.ack Acknowledge code indicating the overall success of the request. Can be one of the following values:
  • SUCCESS – Operation completed successfully.
  • FAILURE – Operation failed.
responseEnvelope.timestamp Timestamp that identifies when the response was sent.
responseEnvelope.correlationId Correlation ID. Used only by Merchant Technical Support.
purchaseId Payson purchaseId for this payment.
senderEmail The sender's email address.
status The status of the payment. Can be one of the following values:
  • 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.
  • INCOMPLETE - Obsolete, this status is not used anymore. Some transfers succeeded and some failed for a parallel payment.
  • ERROR - The payment failed and all attempted transfers failed or all completed transfers were successfully reversed.
  • EXPIRED - A payment requiring approval was not executed within 3 hours.
  • REVERSALERROR – One or more transfers failed when attempting to reverse a payment.
  • ABORTED - The payment was aborted before any money were transferred.
type Type of payment:
  • TRANSFER - This payment is a Payson Direct payment.
  • GUARANTEE - This is a Payson Guarantee payment.
  • INVOICE - This is a Payson Invoice payment.
guaranteeStatus The status of an ongoing Payson Guarantee payment. This is only set if type is GUARANTEE. It can be one of the following values:
  • WAITINGFORSEND
  • WAITINGFORACCEPTANCE
  • WAITINGFORRETURN
  • WAITINGFORRETURNACCEPTANCE
  • RETURNNOTACCEPTED
  • NOTRECEIVED
  • RETURNNOTRECEIVED
  • MONEYRETURNEDTOSENDER
  • RETURNACCEPTED
guaranteeDeadlineTimestamp Timestamp that identifies when the next guarantee deadline is due, if one exists.
invoiceStatus The status of an ongoing Payson Invoice payment. This is only set if type is INVOICE. It can be one of the following values:
  • PENDING
  • ORDERCREATED
  • CANCELED
  • SHIPPED
  • DONE
  • CREDITED
custom A free-form field submitted with the Pay request.
trackingId Your own invoice or tracking id submitted with the Pay request.
receiverList.receiver(n).email Email address of the receiver.
receiverList.receiver(n).amount The amount to transfer to this receiver.
receiverList.receiver(n).primary Determines whether this is the primary receiver or not.

It is one of the following values:
  • true – primary receiver
  • false – secondary receiver
Note: At most one primary receiver is specified and it is only specified in chained payments. This field is not included in a simple.
currencyCode A three-character currency code.

It is one of the following values:
  • SEK (default)
  • EUR
receiverFee The fee charged the receiver of the payment

Shipping address

Invoice 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.
shippingAddress.name The name of the shipment's receiver.
shippingAddress.streetAddress The shipment receiver's street address.
shippingAddress.postalCode The shipment receiver's postal code.
shippingAddress.city The shipment receiver's city.
shippingAddress.country The shipment receiver's country.

PaymentUpdate request

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

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

Parameter Description
token (Required) The token obtained when creating the payment.

Restrictions
GUID, 38 characters.

action (Required) Action to take for this payment.

Must be one of the following values:

  • CANCELORDER - Cancel an order before it is shipped and thereby canceling the entire payment.
    Note: Only possible if type is INVOICE and invoiceStatus is ORDERCREATED.
  • SHIPORDER - Ship an order and thereby convert it into an invoice. The sender will be notified by Payson that an invoice has been created.
    Note: Only possible if type is INVOICE and invoiceStatus is ORDERCREATED.
  • CREDITORDER - Credit an order that has been shipped. A credit invoice will be issued for the entire invoice.
    Note: The full amount including Payson's fee will be drawn from the receiver account. If the receiver account has insufficient funds it is not possible to credit the order. If Payson has not yet settled money to the receiver, the fee will still be drawn from the account. Only possible if type is INVOICE and invoiceStatus is SHIPPED or DONE.
  • REFUND - Refunds a Payson Direct payment to the sender. If the sender deposited a part of the amount it will be refunded to the origin (credit card/bank) if the origin supports it. Remaining parts will be refunded to the sender's Payson account.
    Note: Only possible if type is DIRECT.
  • CANCELPAYMENT - Cancels a pending Payson Direct payment, meaning the associated token can not be used to complete the payment.

PaymentUpdate Response Parameters

Parameter Description
responseEnvelope.ack Acknowledge code indicating the overall success of the request.

Can be one of the following values:
  • SUCCESS – Operation completed successfully
  • FAILURE – Operation failed
responseEnvelope.timestamp Timestamp that identifies when the response was sent.
responseEnvelope.correlationId Correlation ID. Used only by Merchant Technical Support.

Instant Payment Notification (IPN)

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 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 for all status changes, even when a payment fails.

You must
  • validate the IPN content
  • 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/

Parameter Description
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

Description
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 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.

Error Codes

Error Response Parameters

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

Parameter Description
errorList.error(n).errorId A number that uniquely identifies an error.
errorList.error(n).message A description of errorId.
errorList.error(n).parameter Indicates which submitted parameter caused the error. Only included where appropriate.

Error Codes

Code Message
500000 System error.
520002 Internal error.
520003 Authentication failed; Credentials were not valid.
520004 The merchant account is restricted.
520005 The merchant account is locked.
520006 The requested API endpoint is unknown.
529038 Error while executing payment.
539041 An email account is not receive enabled.
539043 An email account is not send enabled.
559044 A receiver's preferences denied the payment.
560027 Unrecognized fees payer type.
579007 Payment request number of receivers exceeds the maximum.
579008 Number of primary receivers exceeds 1.
579017 Primary receiver amount for chained payment must not be less than sum of other receiver amounts.
579018 A primary receiver must be specified if more than one receiver is specified
579033 Sender and each receiver must all have different accounts.
579040 Two receivers belong to the same Payson user account.
579042 The tracking ID already exists and cannot be duplicated.
579045 This request would exceed the receiving limit for an account.
579047 This request would exceed the purse limit for an account.
579048 This request would exceed the sending limit for an account.
579049 The payment request you are looking for was not found in our system.
580001 Invalid request - the request did not pass our basic validation.
580021 Invalid parameter - too long.
580022 Your request was invalid. Check the parameter of the error to see which is invalid.
580023 A receiver was given more than once in the request.
580027 Unsupported currency code.
580028 A URL supplied with the request is malformed.
580029 A required parameter was not provided. Check the error parameter list.
580030 The amount is below the minimum limit.
589018 Invalid pay key.
589052 The transaction ID was not found in our system.
589053 All payment methods have been disabled for this combination of funding constraint, merchant and receiver.
590001 The total amount specified for receivers does not match the total amount specified by the order items.
590005 Not all related order item parameters where specified. All or none of unitPrice, quantity, taxPercentage and sku must be set.
590006 Invoice requires one receiver.
590007 Invoice requires fee on receiver.
590008 Invoice requires that order items are specified.
590009 Invoice payments are not available to this merchant.
590010 The requested action is not possible in the current state of the payment.
590011 The amount on the invoice is below the minimum limit.
590012 Invoice does not support the selected currency.
590013 The invoice fee out of the valid range (0-30 SEK).
590014 The invoice fee can only be specified for invoices.
590015 The receiver is not allowed to receive invoices.
590016 The sender and receiver is the same user.
590017 Invoice is frozen and cannot be updated.
590018 The requested action is not possible for the current type of payment.
590020 A primary receiver is required for this kind of payment.
590021 The funding constraint INVOICE cannot be combined with other funding constraints.

Code examples

The examples make use of libraries implemented by Payson, which can be found at github (C#, PHP).

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);
                    

The paysonApi object contains methods for making requests to Paysons API endpoints. All input and response classes can be found in the namespaces PaysonIntegration.Data and PaysonIntegration.Response respectively.

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 issuing pull requests to us at GitHub.

Initializing payments

To initialize a payment you create an object of type PayData with the parameters needed for the payment type, then invoke MakeyPayRequest on PaysonApi.

If the call is successful, the response object will contain the payment token. This token is your unique handle for this payment request at Payson. You need this token to redirect your customer to Payson to complete the payment.

If the call is not successful, we will respond with a list of error messages. See Error Codes.

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.FirstName = "sender_first_name";
paymentSender.LastName = "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.FirstName = "sender_first_name";
paymentSender.LastName = "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 details

To get details about a payment you invoke MakePaymentDetailsRequest on PaysonApi with the payment token as parameter.

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 changes its state. 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 / sandbox

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):
4
API Password (MD5-key):
2acab30d-fe50-426f-90d7-8c60a7eb31d4
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
Method/Action Test URL
Pay Forward URL https://test-www.payson.se/paysecure/?token={token}
Pay Endpoint https://test-api.payson.se/1.0/Pay/
PaymentDetails Endpoint https://test-api.payson.se/1.0/PaymentDetails/
PaymentUpdate Endpoint https://test-api.payson.se/1.0/PaymentUpdate/
Validate Endpoint https://test-api.payson.se/1.0/Validate/

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.

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.

Revision History

Date Version Description
2013-12-10 1.18 Added support for "ShowReceiptPage" which if 'false' will not show the receipt page in checkout. Default is 'true'.
2013-10-24 1.17 Clarification about returnUrl, cancelUrl and ipnNotificationUrl in Initialize payment
2013-10-14 1.16 PaymentUpdate method extended with ability to cancel a pending payment
2013-05-14 1.15 Added information about receiverFee in PaymentDetails
2013-02-28 1.14 Changed information about fees
2013-02-01 1.13 Changed information about maximum invoice fee
2012-12-12 1.12 Clarification and rewording of the test information, removed parallel payment information and added new error code 590020.
2012-10-19 1.11 Information about test API
2012-08-28 1.10 Cosmetic changes
2012-08-23 1.9 Added missing error code.
2012-08-01 1.8 Added a comment about IPN only possible on port 80 and 443.
2012-07-23 1.7 Added the PAYSON-APPLICATION-ID header. Clarified feesPayer parameter.
2012-04-25 1.6 A review of the initial parts of the documentation has been made.
2011-10-18 1.5 Documentation regarding parameters to PAY has been reviewed, primarily regarding the different callback URLs.
2011-03-28 1.4 Code examples for integrating with the Payson API for C# and PHP.
2011-03-24 1.3 The general integration procedure description has been reviewed and updated. Every parameter description has been reviewed in order to be up to date with the current API.
2010-09-27 1.2 PaymentUpdate method was added. This method is used to handle the state changes for the invoice payment type.
2010-09-16 1.1 OrderItemList was added. These parameters are required for invoice payments.
2010-02-26 1.0 Validate method was added. This is used to validate ipnNotificationUrl Callbacks.
2009-10-14 0.9 Revised draft for version 0.9
2009-09-25 0.8 Revised draft for version 0.8
2009-08-13 0.7 Revised draft for version 0.7