Skip to main content

Authentication

The Transfer API supports two authentication methods for secure access.

MAC Access Authentication​

MAC (Message Authentication Code) Access Authentication is based on OAuth 2.0 MAC Tokens specification. This is the primary authentication method for the Transfer API.

Getting API Credentials​

Before you can use MAC authentication, you need to:

  1. Contact Paysera client support to initiate the onboarding process
  2. Sign the required agreements with Paysera (provided by our client support team)
  3. Receive your API credentials - These will be provided by our client support team and include:
    • client_id - Your unique client identifier
    • mac_key - Secret key for generating authentication signatures
    • mac_algorithm - Algorithm used for MAC calculation (e.g., hmac-sha-256)
info

API credentials are configured and issued by Paysera. Clients cannot self-configure or generate these credentials.

Alternative: SSL Client Certificate​

During the onboarding process, you may optionally choose to use SSL client certificate authentication instead of MAC authentication. If you opt for this method, provide your SSL client certificate to Paysera client support. The certificate will be used to authenticate all requests from your end, replacing the need for MAC credentials.

Requirements​

  • client_id - Your unique client identifier (provided by Paysera)
  • mac_key - Secret key for generating authentication signatures (provided by Paysera)
  • mac_algorithm - Algorithm used for MAC calculation (provided by Paysera)

Authentication Process​

  1. Calculate the current UNIX timestamp
  2. Generate a random nonce (unique string)
  3. Create an authorization header with:
    • id - Your client_id
    • ts - UNIX timestamp
    • nonce - Random string
    • mac - Calculated hash value
    • ext - Optional extensions

Example Authorization Header​

Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="Bp22nWw9qFsz7ux5xOYkCIYJjXAz8mhxTSfJsoOKV3A="

SSL Client Certificate Authentication​

SSL Client Certificate Authentication is an alternative authentication method that can be used instead of MAC authentication.

How It Works​

  • You provide your SSL certificate to Paysera client support during the onboarding process
  • Your private key remains with you and is never shared with Paysera
  • The certificate is used to authenticate your requests at the SSL/TLS layer
  • When using certificate authentication, MAC credentials are not required

Setup Process​

  1. Generate your SSL certificate (if you don't already have one)
  2. Provide the certificate to Paysera client support during the onboarding process
  3. Configure your API client to use the certificate for HTTPS requests
  4. Keep your private key secure - it should never be shared with anyone, including Paysera
warning

Keep your mac_key secret at all times. Anyone with access to this key can make API calls on your behalf.

MAC Calculation Details​

Normalized Request String​

The MAC value is calculated from a normalized request string and your mac_key. The normalized request string is constructed by concatenating the following elements, each followed by a newline character (\n):

  1. Timestamp - UNIX timestamp
  2. Nonce - Random string
  3. HTTP Method - In uppercase (GET, POST, PUT, DELETE)
  4. Request URI - The path component of the request URL
  5. Host - Request host in lowercase
  6. Port - Always 443 for HTTPS
  7. Extension (ext) - URL-encoded string containing extra parameters (can be empty)

Example Normalized Request String​

For a GET request to /transfer/rest/v1/transfers/10145:

1343811600\n
nQnNaSNyubfPErjRO55yaaEYo9YZfKHN\n
GET\n
/transfer/rest/v1/transfers/10145\n
wallet.paysera.com\n
443\n
\n
Important

A newline character (\n) must be added after each element, including after the last one (even if it's an empty string).

MAC Calculation Algorithm​

If your mac_algorithm is hmac-sha-256, the MAC is calculated using the HMAC algorithm with SHA-256:

mac = HMAC-SHA256(mac_key, normalizedRequestString)

The result is a binary value that must be base64 encoded.

$normalizedString = implode("\n", [
    $timestamp,
    $nonce,
    'GET',
    '/transfer/rest/v1/transfers/10145',
    'wallet.paysera.com',
    '443',
    '' // ext parameter (empty in this case)
]) . "\n";

$mac = base64_encode(hash_hmac('sha256', $normalizedString, $macKey, true));
Extension (ext) Parameter

The ext parameter can contain:

  • body_hash - SHA-256 hash of the request body (base64 encoded), required for POST/PUT requests with body
  • project_id - Your project identifier (optional)
  • location_id - Your location identifier (optional)

Parameters in ext are URL-encoded. If there's no request body, body_hash should be omitted.

Example with body_hash​

ext="body_hash=47DEQpj8HBSa%2B%2FTImW%2B5JCeuQeRkm5NMpJWZG3hSuFU%3D"

Calculating body_hash​

$bodyHash = base64_encode(hash('sha256', $requestBody, true));
$ext = 'body_hash=' . urlencode($bodyHash);

Complete Authorization Header Example​

GET /transfer/rest/v1/transfers/10145 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera TransferApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="Bp22nWw9qFsz7ux5xOYkCIYJjXAz8mhxTSfJsoOKV3A="
Nonce Generation

The nonce must be a randomly generated string using only these characters:

  • ASCII printable characters: %x20-21 / %x23-5B / %x5D-7E
  • Typically 32 characters long
  • Must be unique for each request

Example Nonce Generation​

function generateNonce($length = 32) {
    $characters = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
    $nonce = '';
    for ($i = 0; $i < $length; $i++) {
        $nonce .= $characters[rand(0, strlen($characters) - 1)];
    }
    return $nonce;
}