Payments

Create payment orders and payment links using the SDK.

The Payments facade handles order creation, payment links, and payment method queries.

Creating a Payment

The typical payment flow:

1. Build the order request from typed values
2. Build the payment link request
3. Call initiatePayment() to create both

Complete Example

<?php

use Paysera\CheckoutSdk\SdkFacadeBuilder;
use Paysera\CheckoutSdk\Entity\PaymentApiCredentials;
use Paysera\CheckoutSdk\Entity\Metadata;
use Paysera\CheckoutSdk\Entity\PaymentOrderSource;
use Paysera\CheckoutSdk\Entity\PaymentOrder\Purchase;
use Paysera\CheckoutSdk\Entity\PaymentOrder\RedirectUrls;
use Paysera\CheckoutSdk\Entity\PaymentLink\Experience;

// Initialize and authenticate
$sdkFacade = (new SdkFacadeBuilder())->build();
$sdkFacade->getAuthorizationFacade()->authorize(
    new PaymentApiCredentials('client-id', 'client-secret')
);

$paymentsFacade = $sdkFacade->getPaymentsFacade();

// Build order request
$orderRequest = $paymentsFacade->buildPaymentOrderCreateRequestFromValues(
    new Purchase('ORDER-12345', 2500, 'EUR'),  // 25.00 EUR in cents
    new Metadata(
        'https://your-site.paysera.test',      // referer (mandatory)
        'my-cms',                              // platform
        '2.0.0',                               // platform_version
        'paysera-plugin',                      // plugin_name
        '1.0.0'                                // plugin_version
    ),
    new RedirectUrls(
        'https://your-site.paysera.test/checkout/success',
        'https://your-site.paysera.test/checkout/failure',
        'https://your-site.paysera.test/webhooks/paysera',
        'https://your-site.paysera.test/cart'  // optional "back to shop" URL
    ),
    PaymentOrderSource::CHECKOUT_PAGE
);

// Build payment link request
$linkRequest = $paymentsFacade->buildPaymentLinkCreateRequest([
    'name' => 'Order #12345',
    'lifetime' => 3600,          // 1 hour
    'metadata' => [
        'referer' => 'https://your-site.paysera.test',
    ],
    'experience' => [
        'language' => 'en',
        'payment_flow' => Experience::PAYMENT_FLOW_DIRECT,
    ],
    'payer_information' => [
        'name' => 'John Doe',
        'email' => 'johndoe@paysera.test',
    ],
    'purchase' => [
        'amount' => 2500,        // Must match order amount
    ],
]);

// Create payment
$response = $paymentsFacade->initiatePayment($orderRequest, $linkRequest);

// Redirect customer
$paymentUrl = $response->getPaymentUrl();
header('Location: ' . $paymentUrl);
exit;

Order Request Parameters

buildPaymentOrderCreateRequestFromValues() takes typed value objects:

Argument	Type	Required	Description
$purchase	PaymentOrder\Purchase	Yes	reference, amount (minor units), currency
$metadata	Metadata	Yes	referer is mandatory; platform and plugin fields are optional
$redirectUrls	PaymentOrder\RedirectUrls	No	success, failure, callback and optional cancel URL
$source	string	No	One of the PaymentOrderSource values

use Paysera\CheckoutSdk\Entity\Metadata;
use Paysera\CheckoutSdk\Entity\PaymentOrderSource;
use Paysera\CheckoutSdk\Entity\PaymentOrder\Purchase;
use Paysera\CheckoutSdk\Entity\PaymentOrder\RedirectUrls;

$orderRequest = $paymentsFacade->buildPaymentOrderCreateRequestFromValues(
    new Purchase('ORDER-123', 2500, 'EUR'),
    new Metadata('https://your-site.paysera.test', 'woocommerce', '8.0.0', 'paysera-checkout', '1.0.0'),
    new RedirectUrls(
        'https://your-site.paysera.test/success',
        'https://your-site.paysera.test/failure',
        'https://your-site.paysera.test/webhook'
    ),
    PaymentOrderSource::CHECKOUT_PAGE
);

Payment Order Source

Constant	Value	Description
PaymentOrderSource::CHECKOUT_PAGE	checkout_page	Standard checkout page
PaymentOrderSource::PRODUCT_PAGE_EXPRESS_CHECKOUT	product_page_express_checkout	Express checkout started from a product page

Any other value is rejected with a ValidationException.

Raw-array construction is deprecated

buildPaymentOrderCreateRequest([...]) is deprecated since 2.2.0. It does not validate the source allow-list, and any unrecognized metadata.* key is forwarded verbatim as custom metadata — a typo such as referrer instead of referer is silently sent as-is. Use buildPaymentOrderCreateRequestFromValues() instead.

Payment Link Request Parameters

use Paysera\CheckoutSdk\Entity\PaymentLink\Experience;

$linkRequest = $paymentsFacade->buildPaymentLinkCreateRequest([
    // Optional display name
    'name' => 'Order #12345',

    // Link validity in seconds
    'lifetime' => 3600,

    // Mandatory origin URL of the request
    'metadata' => [
        'referer' => 'https://your-site.paysera.test',
    ],

    // Customer experience settings
    'experience' => [
        'language' => 'en',              // UI language
        'payment_flow' => Experience::PAYMENT_FLOW_DIRECT,
    ],

    // Pre-selected payment method
    'payment_details' => [
        'key' => 'swedbank',             // Payment method key
        'purpose' => 'Order #12345',     // Payment purpose text
        'country_code' => 'LT',          // Country for filtering
    ],

    // Customer information
    'payer_information' => [
        'name' => 'John Doe',
        'email' => 'johndoe@paysera.test',
    ],

    // Payment amount (usually matches order)
    'purchase' => [
        'amount' => 2500,
    ],
]);

Payment Flow Options

Flow	Constant	Value	Description
Direct	Experience::PAYMENT_FLOW_DIRECT	direct_payment	Skip method selection, redirect directly to payment method
Checkout	Experience::PAYMENT_FLOW_CHECKOUT	paysera_checkout	Show Paysera checkout page with payment method selection

Response Object

$response = $paymentsFacade->initiatePayment($orderRequest, $linkRequest);

// Get the payment URL for customer redirect
$paymentUrl = $response->getPaymentUrl();

// Get order ID for reference
$orderId = $response->getOrderId();

// Get link ID
$linkId = $response->getLinkId();

// Get expiration time (?DateTimeImmutable)
$expiredAt = $response->getExpiredAt();

// Get creation time (DateTimeImmutable)
$createdAt = $response->getCreatedAt();

Getting Payment Methods

All Available Methods

$methods = $paymentsFacade->getPaymentMethods();

foreach ($methods as $method) {
    echo $method->getKey() . ': ' . $method->getTitle() . "\n";
}

Filtered by Amount/Currency

use Paysera\CheckoutSdk\Entity\PaymentMethodFilter;

// Only methods that support 25 EUR transactions
$filter = new PaymentMethodFilter(2500, 'EUR');

$filteredMethods = $paymentsFacade->getPaymentMethods($filter);

Both arguments are mandatory. An amount below 1 or an unsupported currency raises a ValidationException.

Method Properties

foreach ($methods as $method) {
    $key = $method->getKey();                      // 'swedbank'
    $title = $method->getTitle();                  // 'Swedbank'
    $description = $method->getDescription();      // Method description
    $type = $method->getType();                    // Method type
    $flow = $method->getFlow();                    // 'redirect' or 'direct'
    $countries = $method->getAvailableCountries(); // PaymentCountryCollection
    $logoUrl = $method->getLogoUrl();              // Logo URL served by the API
}

Separate Order and Link Creation

For more control, create the order and the link separately:

// Create order first
$orderResponse = $paymentsFacade->createPaymentOrder($orderRequest);

// Create link for the created order
$linkRequest = $paymentsFacade->buildPaymentLinkCreateRequest([
    'name' => 'Order #12345',
    'lifetime' => 3600,
    'metadata' => [
        'referer' => 'https://your-site.paysera.test',
    ],
    'purchase' => ['amount' => 2500],
]);

$linkRequest
    ->setOrderId($orderResponse->getOrderId())
    ->getPurchase()->setAmount($orderResponse->getPurchase()->getAmount())
;

$linkResponse = $paymentsFacade->createPaymentLink($linkRequest);
$paymentUrl = $linkResponse->getPaymentUrl();

Environment and Payment Statuses

$environment = $paymentsFacade->getPaymentApiEnvironment();
$isSandbox = $environment->isSandbox();

$statuses = $paymentsFacade->getPaymentStatuses();
$isValid = $paymentsFacade->isPaymentStatusValid('settled');

Valid payment statuses are initiated, awaiting_authorization, authorized, processing, pending_settlement, on_hold, settled, failed, rejected, cancelled, expired, refunded and chargeback. See Payment Statuses for what each one means.

Error Handling

use Paysera\CheckoutSdk\Exception\IntegrationException;
use Paysera\CheckoutSdk\Exception\ValidationException;

try {
    $response = $paymentsFacade->initiatePayment($orderRequest, $linkRequest);
} catch (ValidationException $e) {
    // Invalid request parameters — safe to surface as a client error
    error_log('Validation error: ' . $e->getMessage());

    return ['status' => 400, 'error' => 'Invalid payment request. Please try again.'];
} catch (IntegrationException $e) {
    // API or network error — retry or fall back to another payment option
    error_log('Payment API error: ' . $e->getMessage());

    return ['status' => 503, 'error' => 'Payment service temporarily unavailable.'];
}

Never surface the raw exception message to the payer — it may carry API detail. IntegrationException already extracts the user-facing error_description for client errors, so log the exception and show your own copy.

Full Integration Example

Laravel-flavoured service — route() and config() are framework helpers; substitute your own URL and configuration sources.

<?php

use Paysera\CheckoutSdk\SdkFacade;
use Paysera\CheckoutSdk\Entity\Metadata;
use Paysera\CheckoutSdk\Entity\PaymentOrderSource;
use Paysera\CheckoutSdk\Entity\PaymentOrder\Purchase;
use Paysera\CheckoutSdk\Entity\PaymentOrder\RedirectUrls;

class CheckoutService
{
    private SdkFacade $sdkFacade;

    public function __construct(SdkFacade $sdkFacade)
    {
        $this->sdkFacade = $sdkFacade;
    }

    public function createPayment(Order $order, Customer $customer): string
    {
        $paymentsFacade = $this->sdkFacade->getPaymentsFacade();

        $orderRequest = $paymentsFacade->buildPaymentOrderCreateRequestFromValues(
            new Purchase($order->reference, $order->total_cents, $order->currency),
            new Metadata(config('app.url')),
            new RedirectUrls(
                route('checkout.success', ['order' => $order->id]),
                route('checkout.failure', ['order' => $order->id]),
                route('webhooks.paysera')
            ),
            PaymentOrderSource::CHECKOUT_PAGE
        );

        $linkRequest = $paymentsFacade->buildPaymentLinkCreateRequest([
            'name' => "Order #{$order->reference}",
            'lifetime' => 3600,
            'metadata' => ['referer' => config('app.url')],
            'experience' => ['language' => $customer->locale],
            'payer_information' => [
                'name' => $customer->name,
                'email' => $customer->email,
            ],
            'purchase' => ['amount' => $order->total_cents],
        ]);

        $response = $paymentsFacade->initiatePayment($orderRequest, $linkRequest);

        // Store Paysera IDs
        $order->paysera_order_id = $response->getOrderId();
        $order->paysera_link_id = $response->getLinkId();
        $order->save();

        return $response->getPaymentUrl();
    }
}