PHP

Oficjalny SDK PHP dla bramki płatności Cost+. Upraszcza przepływ przekierowań HPP (hostowanej strony płatności), podpisywanie HMAC i weryfikację webhooków.

Funkcje

Zero zewnętrznych zależności — używa tylko wbudowanych rozszerzeń PHP (curl, json, hash)
PHP 8.1+ z właściwościami readonly, nazwanymi argumentami i ścisłymi typami
Generowanie podpisów HMAC-SHA256 i weryfikacja w stałym czasie przez hash_equals
Automatyczne mapowanie snake_case/camelCase między API a SDK
Parsowanie webhooków + weryfikacja zamówienia przez API
Testowany na PHP 8.1, 8.2 i 8.3

Wymagania

PHP 8.1 lub nowszy
Rozszerzenia: curl, json (oba wbudowane w standardowe PHP)
Konto sprzedawcy Cost+ — dashboard.costplus.io

Instalacja

composer require nopayn/sdk

Szybki start

1. Zainicjalizuj klienta

use NoPayn\NoPaynClient;

$nopayn = new NoPaynClient([
    'apiKey'     => 'your-api-key',
    'merchantId' => 'your-project',
]);

2. Utwórz płatność i przekieruj na HPP

$result = $nopayn->generatePaymentUrl([
    'amount'           => 1295,            // 12,95 EUR w centach
    'currency'         => 'EUR',
    'merchantOrderId'  => 'ORDER-001',
    'description'      => 'Premium Widget',
    'returnUrl'        => 'https://shop.example.com/success',
    'failureUrl'       => 'https://shop.example.com/failure',
    'webhookUrl'       => 'https://shop.example.com/webhook',
    'locale'           => 'en-GB',
    'expirationPeriod' => 'PT30M',
]);

// Przekieruj klienta
// $result['orderUrl']   → HPP (klient wybiera metodę płatności)
// $result['paymentUrl'] → bezpośredni link do metody płatności pierwszej transakcji
// $result['signature']  → HMAC-SHA256 do weryfikacji
// $result['orderId']    → UUID zamówienia NoPayn
header('Location: ' . ($result['paymentUrl'] ?? $result['orderUrl']));

3. Obsłuż webhook

$rawBody  = file_get_contents('php://input');
$verified = $nopayn->verifyWebhook($rawBody);

echo $verified['order']['status']; // 'completed', 'cancelled', itp.
echo $verified['isFinal'];        // true gdy zamówienie się nie zmieni

if ($verified['order']['status'] === 'completed') {
    // Zrealizuj zamówienie
}

http_response_code(200);

Dokumentacja API

`new NoPaynClient(array $config)`

Parametr	Typ	Wymagany	Domyślnie
`apiKey`	`string`	Tak	—
`merchantId`	`string`	Tak	—
`baseUrl`	`string`	Nie	`https://api.nopayn.co.uk`

`$client->createOrder(array $params): array`

Tworzy zamówienie przez POST /v1/orders/.

Parametr	Typ	Wymagany	Opis
`amount`	`int`	Tak	Kwota w najmniejszej jednostce waluty (centy)
`currency`	`string`	Tak	Kod ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nie	Twoja wewnętrzna referencja zamówienia
`description`	`string`	Nie	Opis zamówienia
`returnUrl`	`string`	Nie	Przekierowanie po pomyślnej płatności
`failureUrl`	`string`	Nie	Przekierowanie przy anulowaniu/wygaśnięciu/błędzie
`webhookUrl`	`string`	Nie	Asynchroniczne powiadomienia o zmianie statusu
`locale`	`string`	Nie	Język HPP (`en-GB`, `de-DE`, `nl-NL`, itp.)
`paymentMethods`	`string[]`	Nie	Filtruj metody HPP
`expirationPeriod`	`string`	Nie	Czas trwania ISO 8601 (`PT30M`)

Dostępne metody płatności: credit-card, apple-pay, google-pay, vipps-mobilepay

`$client->getOrder(string $orderId): array`

Pobiera szczegóły zamówienia przez GET /v1/orders/{id}/.

`$client->createRefund(string $orderId, int $amount, ?string $description = null): array`

Dokonuje pełnego lub częściowego zwrotu przez POST /v1/orders/{id}/refunds/.

`$client->generatePaymentUrl(array $params): array`

Metoda pomocnicza, która tworzy zamówienie i zwraca:

[
    'orderId'    => string,   // UUID zamówienia NoPayn
    'orderUrl'   => string,   // URL HPP
    'paymentUrl' => ?string,  // Bezpośredni URL płatności (pierwsza transakcja)
    'signature'  => string,   // HMAC-SHA256 z amount:currency:orderId
    'order'      => array,    // Pełny obiekt zamówienia
]

`$client->generateSignature(int $amount, string $currency, string $orderId): string`

Generuje podpis HMAC-SHA256 w formacie hex.

`$client->verifySignature(int $amount, string $currency, string $orderId, string $signature): bool`

Weryfikacja HMAC-SHA256 w stałym czasie.

`$client->verifyWebhook(string $rawBody): array`

Parsuje treść webhooka, następnie wywołuje GET /v1/orders/{id}/, aby zweryfikować rzeczywisty status.

Samodzielne narzędzia HMAC

use NoPayn\Signature;

$sig = Signature::generate('your-api-key', 1295, 'EUR', 'order-uuid');
$ok  = Signature::verify('your-api-key', 1295, 'EUR', 'order-uuid', $sig);

Obsługa błędów

use NoPayn\Exceptions\ApiException;
use NoPayn\Exceptions\NoPaynException;
use NoPayn\Exceptions\WebhookException;

try {
    $nopayn->createOrder(['amount' => 100, 'currency' => 'EUR']);
} catch (ApiException $e) {
    echo $e->getStatusCode(); // 401, 400, itp.
    print_r($e->getErrorBody()); // Surowa odpowiedź błędu API
} catch (NoPaynException $e) {
    echo $e->getMessage(); // Błąd sieci lub parsowania
}

Statusy zamówień

Status	Końcowy?	Opis
`new`	Nie	Zamówienie utworzone
`processing`	Nie	Płatność w toku
`completed`	Tak	Płatność zakończona sukcesem — wydaj towar
`cancelled`	Tak	Płatność anulowana przez klienta
`expired`	Tak	Link płatności wygasł
`error`	Tak	Błąd techniczny

Najlepsze praktyki dotyczące webhooków

Zawsze weryfikuj przez API — treść webhooka zawiera tylko identyfikator zamówienia, nigdy status. verifyWebhook() SDK robi to automatycznie.
Zwracaj HTTP 200, aby potwierdzić odbiór. Każdy inny kod powoduje do 10 ponowień (co 2 minuty).
Zaimplementuj zapasowe odpytywanie — dla zamówień starszych niż 10 minut, które nie osiągnęły końcowego statusu, odpytuj getOrder() jako zabezpieczenie.
Bądź idempotentny — możesz otrzymać ten sam webhook wielokrotnie.

Karty testowe

Użyj tych kart w trybie testowym Cost+ (strona testowa):

Karta	Numer	Uwagi
Visa (sukces)	`4111 1111 1111 1111`	Dowolny CVV
Mastercard (sukces)	`5544 3300 0003 7`	Dowolny CVV
Visa (odrzucona)	`4111 1111 1111 1105`	Do Not Honor
Visa (brak środków)	`4111 1111 1111 1151`	Insufficient Funds

Użyj dowolnej przyszłej daty ważności i dowolnego 3-cyfrowego CVC.

Aplikacja demonstracyjna

Aplikacja demonstracyjna oparta na Dockerze jest dołączona w repozytorium GitHub do testowania pełnego przepływu płatności.

Wsparcie

Potrzebujesz pomocy? Skontaktuj się z naszym zespołem wsparcia pod adresem support@costplus.io.

On this page