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 order request
2. Build 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\PaymentLink\Experience;

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

$paymentsFacade = $sdk->getPaymentsFacade();

// Build order request
$orderRequest = $paymentsFacade->buildPaymentOrderCreateRequest([
    'redirect_urls' => [
        'success_url' => 'https://your-site.paysera.net/checkout/success',
        'failure_url' => 'https://your-site.paysera.net/checkout/failure',
        'callback_url' => 'https://your-site.paysera.net/webhooks/paysera',
    ],
    'metadata' => [
        'referrer' => 'https://your-site.paysera.net',
        'platform' => 'my-cms',
        'platform_version' => '2.0.0',
        'plugin_name' => 'paysera-plugin',
        'plugin_version' => '1.0.0',
    ],
    'purchase' => [
        'reference' => 'ORDER-12345',
        'amount' => 2500,        // 25.00 EUR in cents
        'currency' => 'EUR',
    ],
]);

// Build payment link request
$linkRequest = $paymentsFacade->buildPaymentLinkCreateRequest([
    'name' => 'Order #12345',
    'lifetime' => 3600,          // 1 hour
    'experience' => [
        'language' => 'en',
        'payment_flow' => Experience::PAYMENT_FLOW_DIRECT,
    ],
    'payer_information' => [
        'name' => 'John Doe',
        'email' => 'john@your-site.paysera.net',
    ],
    '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

$orderRequest = $paymentsFacade->buildPaymentOrderCreateRequest([
    // Optional - defaults to the project from your JWT token
    'project_id' => 'uuid',              // Your merchant project ID
    'redirect_urls' => [
        'success_url' => 'https://...',  // Redirect on success
        'failure_url' => 'https://...',  // Redirect on failure
        'callback_url' => 'https://...',  // Webhook URL
    ],
    'purchase' => [
        'reference' => 'ORDER-123',       // Your order reference
        'amount' => 2500,                 // Amount in cents
        'currency' => 'EUR',              // ISO 4217 currency
    ],

    // Optional
    'metadata' => [
        'referrer' => 'https://...',          // Origin URL of the request
        'platform' => 'woocommerce',
        'platform_version' => '8.0.0',
        'plugin_name' => 'paysera-checkout',
        'plugin_version' => '1.0.0',
    ],
]);

Payment Link Request Parameters

use Paysera\CheckoutSdk\Entity\PaymentLink\Experience;

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

    // Link validity in seconds (default: 3600)
    'lifetime' => 3600,

    // 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' => 'john@your-site.paysera.net',
    ],

    // 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 (nullable)
$expiredAt = $response->getExpiredAt();

// Get creation time
$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(
    amount: 2500,
    currency: 'EUR'
);

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

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();                  // Payment flow
    $countries = $method->getAvailableCountries(); // PaymentCountryCollection
}

Separate Order and Link Creation

For more control, create order and link separately:

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

// Create link with order ID
$linkRequest = $paymentsFacade->buildPaymentLinkCreateRequest([
    'order_id' => $orderId,
    'name' => 'Order #12345',
    'lifetime' => 3600,
    'purchase' => ['amount' => 2500],
]);

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

Error Handling

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

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

    // Show user-friendly error
    return response()->json([
        'error' => 'Invalid payment request. Please try again.',
    ], 400);

} catch (IntegrationException $e) {
    // API error
    error_log('Payment API error: ' . $e->getMessage());

    // Show generic error
    return response()->json([
        'error' => 'Payment service temporarily unavailable.',
    ], 503);
}

Full Integration Example

<?php

class CheckoutService
{
    private $sdk;

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

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

        $orderRequest = $paymentsFacade->buildPaymentOrderCreateRequest([
            'redirect_urls' => [
                'success_url' => route('checkout.success', ['order' => $order->id]),
                'failure_url' => route('checkout.failure', ['order' => $order->id]),
                'callback_url' => route('webhooks.paysera'),
            ],
            'metadata' => [
                'referrer' => config('app.url'),
            ],
            'purchase' => [
                'reference' => $order->reference,
                'amount' => $order->total_cents,
                'currency' => $order->currency,
            ],
        ]);

        $linkRequest = $paymentsFacade->buildPaymentLinkCreateRequest([
            'name' => "Order #{$order->reference}",
            'lifetime' => 3600,
            '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();
    }
}