Cost+Docs

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/sdk

Rychly 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)

ParameterTypPovinnePredvolene
apiKeystringAno--
merchantIdstringAno--
baseUrlstringNiehttps://api.nopayn.co.uk

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

Vytvori objednavku cez POST /v1/orders/.

ParameterTypPovinnePopis
amountintánoSuma v menovej jednotke ISO 4217 meny (napríklad centy pre EUR)
currencystringAnoISO 4217 kod (EUR, GBP, USD, NOK, SEK)
merchantOrderIdstringNieVasa interna referencia objednavky
descriptionstringNiePopis objednavky
returnUrlstringNiePresmerovanie po uspesnej platbe
failureUrlstringNiePresmerovanie pri zruseni/exspiracii/chybe
webhookUrlstringNieAsynchronne notifikacie o zmene stavu
localestringNieJazyk HPP (en-GB, de-DE, nl-NL, atd.)
paymentMethodsstring[]NieFilter platobnych metod HPP
expirationPeriodstringNieISO 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

StavKoncovy?Popis
newNieObjednavka vytvorena
processingNiePlatba prebieha
completedAnoPlatba uspesna -- doructe tovar
cancelledAnoPlatba zrusena zakaznikom
expiredAnoPlatobny odkaz vyprsal
errorAnoTechnicka chyba

Osvedcene postupy pre webhooky

  1. Vzdy overujte cez API -- payload webhooku obsahuje len ID objednavky, nikdy nie stav. SDK verifyWebhook() to robi automaticky.
  2. Vracajte HTTP 200 na potvrdenie prijatia. Akykolvek iny kod spusti az 10 opakovanych pokusov (2 minuty od seba).
  3. Implementujte zalohu dotazovanie -- pre objednavky starsie ako 10 minut, ktore nedosiahli konecny stav, dotazujte getOrder() ako bezpecnostnu siet.
  4. Budte idempotentni -- ten isty webhook mozete prijat viackrat.

Testovacie karty

Pouzite tieto karty v testovacom rezime Cost+ (sandbox webova stranka):

KartaCisloPoznamky
Visa (uspech)4111 1111 1111 1111Akekolvek CVV
Mastercard (uspech)5544 3300 0003 7Akekolvek CVV
Visa (zamietnutie)4111 1111 1111 1105Do Not Honor
Visa (nedostatok prostriedkov)4111 1111 1111 1151Insufficient 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.

On this page