README

Oficjalne SDK platformy CraftPay dla Laravel.

Dwa moduły w jednym pakiecie:

Instalacja

composer require craftpay/sdk
php artisan vendor:publish --tag=craftpay-config

Moduł Client — własna strona pod API CraftPay

Użyj gdy chcesz wyświetlić sklep CraftPay na swojej stronie albo zbudować własny checkout.

Konfiguracja .env

CRAFTPAY_SHOP_UUID=uuid-twojego-sklepu
CRAFTPAY_API_SECRET=twoj-api-secret   # tylko dla endpointów /me i /transactions

Użycie przez Facade

use CraftPay\Sdk\Client\Facades\CraftPay;

// Informacje o sklepie
$shop       = CraftPay::shop()->get();
$gateways   = CraftPay::shop()->gateways();
$topPlayers = CraftPay::shop()->topPlayers();
$recent     = CraftPay::shop()->recentPurchases();
$news       = CraftPay::shop()->announcements();

// Kategorie i paczki
$categories = CraftPay::categories()->all();
$packages   = CraftPay::categories()->packages(categoryId: 3);  // lub slug
$all        = CraftPay::packages()->all();

// Złożenie zamówienia
$order = CraftPay::orders()->create([
    'package_id' => 7,
    'nickname'   => 'Steve',
    'gateway'    => 'cashbill',
]);
// $order['payment_url'] — przekieruj kupującego tutaj

// Status zamówienia
$status = CraftPay::orders()->status($order['order_token']);

// Walidacja vouchera
$result = CraftPay::vouchers()->validate([
    'code'     => 'PROMO100',
    'nickname' => 'Steve',
]);

// Wymagają api_secret:
$me           = CraftPay::shop()->me();
$transactions = CraftPay::orders()->transactions(['page' => 1, 'status' => 'success']);

Użycie przez Dependency Injection

use CraftPay\Sdk\Client\CraftPayClient;

class ShopController extends Controller
{
    public function __construct(private CraftPayClient $craftpay) {}

    public function index()
    {
        $packages = $this->craftpay->packages()->all();
        return view('shop.index', compact('packages'));
    }
}

Obsługa błędów

use CraftPay\Sdk\Client\Exceptions\CraftPayException;
use CraftPay\Sdk\Client\Exceptions\ShopNotFoundException;

try {
    $shop = CraftPay::shop()->get();
} catch (ShopNotFoundException $e) {
    // Sklep nie istnieje lub jest wyłączony
} catch (CraftPayException $e) {
    // $e->errorCode — kod błędu z API
    // $e->getMessage() — wiadomość
    // $e->getCode() — HTTP status
}

Moduł Gateway — dla hostingów

Użyj gdy chcesz żeby Twój hosting pojawił się jako dostępna bramka płatności w CraftPay.

Jak to działa

CraftPay  ──POST /api/craftpay/payments/create──▶  Twój panel
                                                        │
                                                   (przetwarzasz płatność)
                                                        │
Twój panel ──POST {notify_url}──────────────────▶  CraftPay

Konfiguracja .env

CRAFTPAY_GATEWAY_ENABLED=true
CRAFTPAY_GATEWAY_API_KEY=klucz-ustalony-z-craftpay-adminem

Implementacja drivera

Stwórz klasę implementującą PaymentDriverInterface:

// app/Services/CraftPayDriver.php
use CraftPay\Sdk\Gateway\Contracts\PaymentDriverInterface;
use CraftPay\Sdk\Gateway\Data\CreatePaymentRequest;
use CraftPay\Sdk\Gateway\Data\PaymentResult;

class CraftPayDriver implements PaymentDriverInterface
{
    public function createPayment(CreatePaymentRequest $request): PaymentResult
    {
        // Stwórz płatność w swoim systemie
        $payment = MyPaymentSystem::create([
            'amount'      => $request->amount,       // np. "10.00"
            'currency'    => $request->currency,     // "PLN"
            'description' => $request->description,
            'return_url'  => $request->returnUrl,
        ]);

        // Zwróć ID płatności i URL do którego ma trafić kupujący
        return new PaymentResult(
            paymentId:  (string) $payment->id,
            paymentUrl: $payment->checkout_url,
        );
    }
}

Zarejestruj driver w AppServiceProvider:

use CraftPay\Sdk\Gateway\Contracts\PaymentDriverInterface;

public function register(): void
{
    $this->app->bind(PaymentDriverInterface::class, CraftPayDriver::class);
}

Uruchom migrację:

php artisan vendor:publish --tag=craftpay-migrations
php artisan migrate

Powiadamianie CraftPay o płatności

Gdy kupujący opłaci zamówienie (np. w Twoim webhookу od Przelewy24):

use CraftPay\Sdk\Gateway\Facades\CraftPayGateway;

// Płatność udana
CraftPayGateway::notifyPaid(
    orderId:   $request->input('order_id'),   // UUID z CraftPay
    paymentId: $internalPaymentId,            // Twoje wewnętrzne ID płatności
);

// Płatność nieudana / anulowana
CraftPayGateway::notifyFailed($orderId);

// Sprawdzenie stanu zamówienia
$order = CraftPayGateway::findOrder($orderId);

Endpoint wystawiony automatycznie

Po włączeniu (CRAFTPAY_GATEWAY_ENABLED=true) SDK automatycznie rejestruje:

POST /api/craftpay/payments/create

Podaj ten endpoint adminom CraftPay razem z kluczem API (CRAFTPAY_GATEWAY_API_KEY).

Wymagania

• PHP 8.2+
• Laravel 10 / 11 / 12