Skip to main content

Custom Integration

This guide explains how to integrate the Paysera Checkout API with a custom implementation without using official libraries. Below you will find a detailed specification of the data that is sent and received.

Use the library when possible

If PHP (with the required version) is available on your server, we strongly recommend using the libwebtopay library to generate requests and process callbacks. It handles the encoding and signing steps described below for you.

Prerequisites​

Before you begin, ensure you have:

  • Your project_id and project_password from Obtaining Credentials
  • Ability to make HTTP requests from your application
  • Understanding of request signing and security

Payment Flow Overview​

  1. Create a signed payment request
  2. Redirect customer to Paysera payment page
  3. Customer completes payment

Understanding Request Structure​

Before implementing, it's important to understand how Paysera payment requests work. You send the data to https://www.paysera.com/pay/ using either the GET or POST method. There are always exactly two fields sent: data and sign.

Example URL:

https://www.paysera.com/pay/?data=YOUR_DATA_PARAMETER&sign=YOUR_SIGN_PARAMETER

Generating Request Fields (4 Steps)​

Step 1: Create URL-Encoded String​

Join all parameters into a URL-encoded string. For example:

// Input parameters
{
  'param1': 'abc',
  'param2': 'Some string with symbols %=&'
}

// Result after URL encoding
'param1=abc&param2=Some+string+with+symbols+%25%3D%26'

In PHP, use http_build_query() function. In JavaScript, use URLSearchParams.

Step 2: Base64 Encode​

Encode the result string in base64 encoding:

// Input
'param1=abc&param2=Some+string+with+symbols+%25%3D%26'

// After base64 encoding
'cGFyYW0xPWFiYyZwYXJhbTI9U29tZStzdHJpbmcrd2l0aCtzeW1ib2xzKyUyNSUzRCUyNg=='

In PHP, use base64_encode() function. In JavaScript, use Buffer.from().toString('base64').

Step 3: Make URL-Safe​

Replace "/" with "_" and "+" with "-" to make it URL-safe:

// Input
'MViDYlV7V0iHR2w2OkJjRFFpY11hizJDhk+EZjl/'

// After replacement
'MViDYlV7V0iHR2w2OkJjRFFpY11hizJDhk-EZjl_'

In PHP, use str_replace() or strtr() function.

Step 4: Generate Signature​

Create the sign parameter using MD5 hash:

sign = md5(data + password)

Where:

  • data - the encoded parameters from Step 3
  • password - your project password

Implementation Steps​

The following example is shown in JavaScript, but these steps can be implemented in any programming language.

1. Create Payment Data​

Build the payment data object with required parameters:

const crypto = require('crypto');

const projectid = 'YOUR_PROJECT_ID';
const sign_password = 'YOUR_PROJECT_PASSWORD';

const data = {
    'projectid': projectid,
    'orderid': '12345', // Unique order identifier
    'amount': 1000, // Amount in cents
    'currency': 'EUR',
    'accepturl': '{acceptURL}', // URL to redirect after successful payment
    'cancelurl': '{cancelURL}', // URL to redirect when payment is cancelled
    'callbackurl': '{callbackURL}', // URL to receive payment status notifications
    'version': '1.8',
    'test': 1 // Remove for production
};

2. Sign the Request​

Encode the data as URL parameters and create a signature:

// Convert data to query string format
const result = new URLSearchParams(data).toString();

// Encode as URL-safe base64
const base64Encoded = Buffer.from(result).toString('base64');
const encodedData = base64Encoded.replace(/\//g, '_').replace(/\+/g, '-');

// Create MD5 signature
const sign = crypto.createHash('md5').update(encodedData + sign_password).digest('hex');

3. Generate Payment URL​

Create the final payment URL:

const url = 'https://www.paysera.com/pay/?';
const finalQuery = new URLSearchParams({ data: encodedData, sign: sign }).toString();
const paymentUrl = url + finalQuery;

console.log('Payment URL:', paymentUrl);

Complete Example​

Here's the complete code combining all the steps above:

const crypto = require('crypto');

const projectid = 'YOUR_PROJECT_ID';
const sign_password = 'YOUR_PROJECT_PASSWORD';

const data = {
    'projectid': projectid,
    'orderid': '12345', // Unique order identifier
    'amount': 1000, // Amount in cents
    'currency': 'EUR',
    'accepturl': '{acceptURL}', // URL to redirect after successful payment
    'cancelurl': '{cancelURL}', // URL to redirect when payment is cancelled
    'callbackurl': '{callbackURL}', // URL to receive payment status notifications
    'version': '1.8',
    'test': 1 // Remove for production
};

// Convert data to query string format
const result = new URLSearchParams(data).toString();

// Encode as URL-safe base64
const base64Encoded = Buffer.from(result).toString('base64');
const encodedData = base64Encoded.replace(/\//g, '_').replace(/\+/g, '-');

// Create MD5 signature
const sign = crypto.createHash('md5').update(encodedData + sign_password).digest('hex');

const url = 'https://www.paysera.com/pay/?';
const finalQuery = new URLSearchParams({ data: encodedData, sign: sign }).toString();
const paymentUrl = url + finalQuery;

console.log('Payment URL:', paymentUrl);

Important Notes​

  • Keep your project password secure - never expose it in client-side code
  • Use HTTPS for all URLs to ensure secure communication

Request Parameters​

Below are the most commonly used parameters. For complete documentation, see:

Required Parameters​

ParameterTypeDescription
projectidintegerYour project ID
orderidstringUnique order identifier
amountintegerPayment amount in cents
currencystringCurrency code (EUR, USD, etc.)
accepturlstringURL for successful payment redirect
cancelurlstringURL for cancelled payment redirect
callbackurlstringURL for payment notification
versionstringAPI version (e.g., "1.8" or "1.9")

Optional Parameters​

ParameterTypeDescription
testintegerSet to 1 for test payments
p_firstnamestringCustomer first name
p_lastnamestringCustomer last name
p_emailstringCustomer email
countrystringCustomer country code
langstringInterface language code
paymentstringSpecific payment method code (see Payment Types)

Next Steps​