Authorization

Set up OAuth2 authentication with automatic token management.

The Authorization facade handles OAuth2 authentication with the Paysera API.

Basic Usage

<?php

use Paysera\CheckoutSdk\SdkFacadeBuilder;
use Paysera\CheckoutSdk\Entity\PaymentApiCredentials;

$sdkFacade = (new SdkFacadeBuilder())->build();
$authFacade = $sdkFacade->getAuthorizationFacade();

// Create credentials
$apiCredentials = new PaymentApiCredentials(
    'your-client-id',
    'your-client-secret'
);

// Authenticate
$authToken = $authFacade->authorize($apiCredentials);

// Token is now available for API calls
$accessToken = $authToken->getAccessToken();

How It Works

The authorize() method:

1. Sends credentials to the Paysera auth endpoint
2. Receives a JWT access token and validates its signature
3. Stores the token and credentials in the configured repositories (or memory)
4. Returns the token entity for reference

Credentials Entity

use Paysera\CheckoutSdk\Entity\PaymentApiCredentials;

$apiCredentials = new PaymentApiCredentials(
    'your-client-id',
    'your-client-secret'
);

$clientId = $apiCredentials->getClientId();
$clientSecret = $apiCredentials->getClientSecret();

See Obtaining Credentials for creating a project and generating a client_id / client_secret pair.

Token Entity

use Paysera\CheckoutSdk\Entity\PaymentApiAuthToken;

// After authorization
$authToken = $authFacade->authorize($apiCredentials);

$accessToken = $authToken->getAccessToken();   // JWT string
$environment = $authToken->getEnvironment();   // PaymentApiEnvironment
$isSandbox = $environment->isSandbox();        // bool

// PaymentApiAuthToken is Stringable and casts to the raw access token
$header = 'Bearer ' . $authToken;

Decoded Token Claims

Expiration, project and client identifiers live on the decoded JWT, not on the token entity:

$decodedToken = $authFacade->getDecodedToken();

if ($decodedToken !== null) {
    $projectId = $decodedToken->getProjectId();  // string
    $clientId = $decodedToken->getClientId();    // string
    $expiresAt = $decodedToken->getExpiresAt();  // int (Unix timestamp)
    $issuedAt = $decodedToken->getIssuedAt();    // int (Unix timestamp)
}

getDecodedToken() returns null when no token is stored, and throws IntegrationException when the stored token cannot be decoded.

Re-authorization

When the token has expired, refresh it from the stored credentials:

$freshToken = $authFacade->reauthorize();

This requires a persistent credentials repository — see Installation.

Reading Stored Values

$storedCredentials = $authFacade->getStoredPaymentApiCredentials();  // ?PaymentApiCredentials
$storedToken = $authFacade->getStoredPaymentApiAuthToken();          // ?PaymentApiAuthToken

Both return null when nothing is stored.

Token Persistence

By default, tokens are stored in memory and lost when the script ends. For persistent storage, implement PaymentApiAuthTokenRepositoryInterface and pass it to the builder. See Installation for details.

Error Handling

use Paysera\CheckoutSdk\Exception\IntegrationException;

try {
    $authToken = $authFacade->authorize($apiCredentials);
} catch (IntegrationException $e) {
    // Authentication failed
    error_log('Auth failed: ' . $e->getMessage());

    // Check for specific errors
    if (strpos($e->getMessage(), 'invalid_client') !== false) {
        // Invalid credentials
    } elseif (strpos($e->getMessage(), 'unauthorized') !== false) {
        // Credentials revoked or disabled
    }
}