PHP
Oficialne PHP SDK pre platobnu branu Cost+
Oficialne PHP SDK pre platobnu branu Cost+. Zjednodusuje proces presmerovania HPP (Hosted Payment Page), HMAC podpisovanie payloadov a overovanie webhookov.
Funkcie
- Ziadne externe zavislosti -- pouziva len vstavane PHP rozsirenia (
curl,json,hash) - PHP 8.1+ s readonly vlastnostami, pomenovanymi argumentmi a striktnymi typmi
- HMAC-SHA256 generovanie podpisov a overovanie v konstantnom case cez
hash_equals - Automaticke mapovanie snake_case/camelCase medzi API a SDK
- Parsovanie webhookov + overovanie objednavok na zaklade API
- Testovane na PHP 8.1, 8.2 a 8.3
Poziadavky
- PHP 8.1 alebo novsi
- Rozsirenia:
curl,json(obe su sucastou standardneho PHP) - Ucet obchodnika Cost+ -- dashboard.costplus.io
Instalacia
composer require nopayn/sdkRychly start
1. Inicializacia klienta
use NoPayn\NoPaynClient;
$nopayn = new NoPaynClient([
'apiKey' => 'your-api-key',
'merchantId' => 'your-project',
]);2. Vytvorenie platby a presmerovanie na HPP
$result = $nopayn->generatePaymentUrl([
'amount' => 1295, // €12,95 v centoch
'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',
]);
// Presmerujte zakaznika
// $result['orderUrl'] → HPP (zakaznik si vyberie platobnu metodu)
// $result['paymentUrl'] → priamy odkaz na platobnu metodu prvej transakcie
// $result['signature'] → HMAC-SHA256 na overenie
// $result['orderId'] → NoPayn UUID objednavky
header('Location: ' . ($result['paymentUrl'] ?? $result['orderUrl']));3. Spracovanie webhooku
$rawBody = file_get_contents('php://input');
$verified = $nopayn->verifyWebhook($rawBody);
echo $verified['order']['status']; // 'completed', 'cancelled', atd.
echo $verified['isFinal']; // true, ked sa objednavka uz nezmeni
if ($verified['order']['status'] === 'completed') {
// Vybavte objednavku
}
http_response_code(200);API referencia
new NoPaynClient(array $config)
| Parameter | Typ | Povinne | Predvolene |
|---|---|---|---|
apiKey | string | Ano | -- |
merchantId | string | Ano | -- |
baseUrl | string | Nie | https://api.nopayn.co.uk |
$client->createOrder(array $params): array
Vytvori objednavku cez POST /v1/orders/.
| Parameter | Typ | Povinne | Popis |
|---|---|---|---|
amount | int | áno | Suma v menovej jednotke ISO 4217 meny (napríklad centy pre EUR) |
currency | string | Ano | ISO 4217 kod (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | string | Nie | Vasa interna referencia objednavky |
description | string | Nie | Popis objednavky |
returnUrl | string | Nie | Presmerovanie po uspesnej platbe |
failureUrl | string | Nie | Presmerovanie pri zruseni/exspiracii/chybe |
webhookUrl | string | Nie | Asynchronne notifikacie o zmene stavu |
locale | string | Nie | Jazyk HPP (en-GB, de-DE, nl-NL, atd.) |
paymentMethods | string[] | Nie | Filter platobnych metod HPP |
expirationPeriod | string | Nie | ISO 8601 trvanie (PT30M) |
Dostupne platobne metody: credit-card, apple-pay, google-pay, vipps-mobilepay
$client->getOrder(string $orderId): array
Ziskanie podrobnosti objednavky cez GET /v1/orders/{id}/.
$client->createRefund(string $orderId, int $amount, ?string $description = null): array
Vydanie uplneho alebo ciastocneho vratenia cez POST /v1/orders/{id}/refunds/.
$client->generatePaymentUrl(array $params): array
Pomocna metoda, ktora vytvori objednavku a vrati:
[
'orderId' => string, // NoPayn UUID objednavky
'orderUrl' => string, // HPP URL
'paymentUrl' => ?string, // Priama platobna URL (prva transakcia)
'signature' => string, // HMAC-SHA256 z amount:currency:orderId
'order' => array, // Uplny objekt objednavky
]$client->generateSignature(int $amount, string $currency, string $orderId): string
Generuje HMAC-SHA256 hex podpis.
$client->verifySignature(int $amount, string $currency, string $orderId, string $signature): bool
Overovanie HMAC-SHA256 podpisu v konstantnom case.
$client->verifyWebhook(string $rawBody): array
Parsuje telo webhooku, potom vola GET /v1/orders/{id}/ na overenie skutocneho stavu.
Samostatne HMAC nastroje
use NoPayn\Signature;
$sig = Signature::generate('your-api-key', 1295, 'EUR', 'order-uuid');
$ok = Signature::verify('your-api-key', 1295, 'EUR', 'order-uuid', $sig);Spracovanie chyb
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, atd.
print_r($e->getErrorBody()); // Surova API chybova odpoved
} catch (NoPaynException $e) {
echo $e->getMessage(); // Sietova alebo parsovania chyba
}Stavy objednavok
| Stav | Koncovy? | Popis |
|---|---|---|
new | Nie | Objednavka vytvorena |
processing | Nie | Platba prebieha |
completed | Ano | Platba uspesna -- doructe tovar |
cancelled | Ano | Platba zrusena zakaznikom |
expired | Ano | Platobny odkaz vyprsal |
error | Ano | Technicka chyba |
Osvedcene postupy pre webhooky
- Vzdy overujte cez API -- payload webhooku obsahuje len ID objednavky, nikdy nie stav. SDK
verifyWebhook()to robi automaticky. - Vracajte HTTP 200 na potvrdenie prijatia. Akykolvek iny kod spusti az 10 opakovanych pokusov (2 minuty od seba).
- Implementujte zalohu dotazovanie -- pre objednavky starsie ako 10 minut, ktore nedosiahli konecny stav, dotazujte
getOrder()ako bezpecnostnu siet. - Budte idempotentni -- ten isty webhook mozete prijat viackrat.
Testovacie karty
Pouzite tieto karty v testovacom rezime Cost+ (sandbox webova stranka):
| Karta | Cislo | Poznamky |
|---|---|---|
| Visa (uspech) | 4111 1111 1111 1111 | Akekolvek CVV |
| Mastercard (uspech) | 5544 3300 0003 7 | Akekolvek CVV |
| Visa (zamietnutie) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedostatok prostriedkov) | 4111 1111 1111 1151 | Insufficient Funds |
Pouzite akykolvek buduci datum exspiracie a akykolvek 3-ciselny CVC.
Demo aplikacia
Demo aplikacia na baze Dockeru je zahrnuta v GitHub repozitari na testovanie uplneho platobneho procesu.
Podpora
Potrebujete pomoc? Kontaktujte nas tym podpory na support@costplus.io.