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.

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.

Payson Direct

Example of how to 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);

Use the paymentDetailsResponse.PaymentDetails object to, for instance,
get 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, 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
    // Here you would check the status of the payment and update your system accordingly
}

$content = "the_content_from_the_http_request_to_your_ipn_url";
$validateResponse =  $api->validate($content);
if ($validateResponse->isVerified()){
   // IPN was confirmed by Payson
   // Here you would check the status of the payment and update your system accordingly
}

If the property validateResponse.Success is true, then Payson has confirmed the request. You can use thevalidateResponse.ProcessedIpnMessage to conveniently access data from the IPN message content.