Authentication

The Wallet API supports two primary authentication methods for API access.

Authentication Methods

All API calls must be authenticated. Choose one of these methods:

• MAC Access Authentication - Using shared secret key (most common)
• SSL Client Certificate - Using client certificate (more secure)

HTTPS Required

All requests must use HTTPS protocol. Always verify Paysera server certificate to protect against DNS spoofing and MITM attacks.

MAC Access Authentication

MAC (Message Authentication Code) authentication is based on OAuth 2.0 MAC Tokens specification. This is the most common authentication method.

Getting Credentials:

Before using the API, register your application with Paysera support. You'll receive:

client_id:     wkVd93h2uS
mac_key:       IrdTc8uQodU7PRpLzzLTW6wqZAO6tAMU
mac_algorithm: hmac-sha-256

Keep Secret

The mac_key must be kept secret at all times. Never expose it in client-side code or version control.

Authorization Header:

Each request must include an Authorization header with these parameters:

Parameter	Description
id	Your client ID
ts	UNIX timestamp
nonce	Random string (only chars: %x20-21 / %x23-5B / %x5D-7E)
mac	Calculated hash of request
ext	Extension parameters (optional)

Example Request:

GET /rest/v1/payment/10145 HTTP/1.1
Host: wallet.paysera.com
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="/qxTA8FOgT0Dd0MHh9k/sUQ3Q38ckx8+S0PBxpIuttY="

How to Calculate MAC Value

Calculating MAC Value

The MAC value is calculated from a normalized request string and your mac_key.

Step 1: Create Normalized Request String

Concatenate these elements, each followed by a newline (\n):

1. Timestamp (ts)
2. Nonce
3. HTTP method (uppercase)
4. Request URI
5. Host (lowercase)
6. Port (always 443)
7. Extension parameters (ext)

Example:

1343811600\n
nQnNaSNyubfPErjRO55yaaEYo9YZfKHN\n
GET\n
/rest/v1/payment/10145\n
wallet.paysera.com\n
443\n
\n

Newline After Last Element

Always include newline after the last element, even if it's empty!

Step 2: Calculate HMAC-SHA256

mac = HMAC-SHA256(mac_key, normalizedRequestString)

The result is base64-encoded binary output.

Example Implementation

const crypto = require('crypto');

function calculateMAC(macKey, ts, nonce, method, uri, host, ext = '') {
    const normalized = [
        ts,
        nonce,
        method.toUpperCase(),
        uri,
        host.toLowerCase(),
        '443',
        ext
    ].join('\n') + '\n';
    
    const hmac = crypto.createHmac('sha256', macKey);
    hmac.update(normalized);
    return hmac.digest('base64');
}

// Usage
const mac = calculateMAC(
    'IrdTc8uQodU7PRpLzzLTW6wqZAO6tAMU',
    '1343811600',
    'nQnNaSNyubfPErjRO55yaaEYo9YZfKHN',
    'GET',
    '/rest/v1/payment/10145',
    'wallet.paysera.com'
);

Extension Parameters (ext)

Extension Parameters (ext)

The ext field can contain additional parameters:

Body Hash

For requests with body content, include body_hash:

const bodyHash = crypto
    .createHash('sha256')
    .update(requestBody)
    .digest('base64');

const ext = `body_hash=${encodeURIComponent(bodyHash)}`;

Extra Parameters

Include project_id or location_id when needed:

ext="body_hash=abc123&project_id=1221&location_id=456"

Complete Example with Body

POST /rest/v1/transaction HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="TjBTboV3iZkrUvu6wHxXeflNF0INZ8TZmzK/G8Utj4E=", ext="body_hash=QbSp3xrqzhDpmjuLmGjjmBDdLalG55QEJFX2W1jq3QI%3D"

{
  "beneficiary": "EVP1234567890",
  "amount": 1000
}

---

SSL Client Certificate Authentication

More secure authentication method using client certificates. No additional headers needed for each request.

SSL Certificate Setup Process

1. Generate Private Key:

openssl genrsa -out private.pem 2048

Keep Private Key Secure

Never share your private key, even with Paysera administrators!

2. Create Certificate Request:

openssl req -new -key private.pem -out certificate_request.csr

Fill in the details:

Country Name (2 letter code): LT
State or Province Name: <skip>
Locality Name: Vilnius
Organization Name: UAB Your Company
Organizational Unit Name: <skip>
Common Name: example.com
Email Address: info@example.com

Skip Optional Company Name

Leave "An optional company name" field empty when generating the certificate request.

3. Submit Certificate Request:

Send certificate_request.csr to Paysera support. They will:

1. Sign your certificate
2. Return the signed certificate

4. Use Certificate

Configure your HTTP client to use:

• Signed certificate from Paysera
• Your private key (private.pem)

Example with cURL:

curl --cert certificate.pem \
     --key private.pem \
     https://wallet.paysera.com/rest/v1/user/me

Example with Node.js:

const https = require('https');
const fs = require('fs');

const options = {
    hostname: 'wallet.paysera.com',
    port: 443,
    path: '/rest/v1/user/me',
    method: 'GET',
    key: fs.readFileSync('private.pem'),
    cert: fs.readFileSync('certificate.pem')
};

https.request(options, (res) => {
    res.on('data', (d) => {
        process.stdout.write(d);
    });
}).end();

---

Support

Need help with complex integrations?

Contact: tech_support@paysera.com