Cost+Docs

PHP

Službeni PHP SDK za Cost+ platni pristupnik

Službeni PHP SDK za Cost+ platni pristupnik. Pojednostavljuje tijek preusmjeravanja na HPP (hosted stranicu za plaćanje), HMAC potpisivanje podataka i verifikaciju webhookova.

Značajke

  • Bez vanjskih ovisnosti — koristi samo ugrađena PHP proširenja (curl, json, hash)
  • PHP 8.1+ s readonly svojstvima, imenovanim argumentima i strogim tipovima
  • HMAC-SHA256 generiranje potpisa i verifikacija konstantnim vremenom putem hash_equals
  • Automatsko mapiranje snake_case/camelCase između API-ja i SDK-a
  • Raščlamba webhookova + verifikacija narudžbe temeljena na API-ju
  • Testirano na PHP 8.1, 8.2 i 8.3

Zahtjevi

  • PHP 8.1 ili noviji
  • Proširenja: curl, json (oboje uključeno u standardni PHP)
  • Cost+ trgovački račun — dashboard.costplus.io

Instalacija

composer require nopayn/sdk

Brzi početak

1. Inicijalizirajte klijent

use NoPayn\NoPaynClient;

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

2. Stvorite plaćanje i preusmjerite na HPP

$result = $nopayn->generatePaymentUrl([
    'amount'           => 1295,            // €12.95 in cents
    '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',
]);

// Redirect the customer
// $result['orderUrl']   → HPP (customer picks payment method)
// $result['paymentUrl'] → direct link to the first transaction's payment method
// $result['signature']  → HMAC-SHA256 for verification
// $result['orderId']    → NoPayn order UUID
header('Location: ' . ($result['paymentUrl'] ?? $result['orderUrl']));

3. Obradite webhook

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

echo $verified['order']['status']; // 'completed', 'cancelled', etc.
echo $verified['isFinal'];        // true when the order won't change

if ($verified['order']['status'] === 'completed') {
    // Fulfil the order
}

http_response_code(200);

API referenca

new NoPaynClient(array $config)

ParametarTipObaveznoZadano
apiKeystringDa—
merchantIdstringDa—
baseUrlstringNehttps://api.nopayn.co.uk

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

Stvara narudžbu putem POST /v1/orders/.

ParametarTipObaveznoOpis
amountintDaIznos u manjoj jedinici ISO 4217 valute (na primjer, centi za EUR)
currencystringDaISO 4217 kod (EUR, GBP, USD, NOK, SEK)
merchantOrderIdstringNeVaša interna referenca narudžbe
descriptionstringNeOpis narudžbe
returnUrlstringNePreusmjeravanje nakon uspješnog plaćanja
failureUrlstringNePreusmjeravanje pri poništenju/isteku/grešci
webhookUrlstringNeAsinkrone obavijesti o promjeni statusa
localestringNeJezik HPP-a (en-GB, de-DE, nl-NL itd.)
paymentMethodsstring[]NeFiltriranje HPP načina
expirationPeriodstringNeISO 8601 trajanje (PT30M)

Dostupni načini plaćanja: credit-card, apple-pay, google-pay, vipps-mobilepay

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

Dohvaća detalje narudžbe putem GET /v1/orders/{id}/.

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

Izdaje potpuni ili djelomični povrat putem POST /v1/orders/{id}/refunds/.

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

Praktična metoda koja stvara narudžbu i vraća:

[
    'orderId'    => string,   // NoPayn order UUID
    'orderUrl'   => string,   // HPP URL
    'paymentUrl' => ?string,  // Direct payment URL (first transaction)
    'signature'  => string,   // HMAC-SHA256 of amount:currency:orderId
    'order'      => array,    // Full order object
]

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

Generira HMAC-SHA256 heksadecimalni potpis.

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

Verifikacija HMAC-SHA256 potpisa konstantnim vremenom.

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

Raščlanjuje tijelo webhooka, zatim poziva GET /v1/orders/{id}/ za provjeru stvarnog statusa.

Samostalni HMAC alati

use NoPayn\Signature;

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

Rukovanje greškama

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, etc.
    print_r($e->getErrorBody()); // Raw API error response
} catch (NoPaynException $e) {
    echo $e->getMessage(); // Network or parsing error
}

Statusi narudžbe

StatusKonačan?Opis
newNeNarudžba stvorena
processingNePlaćanje u tijeku
completedDaPlaćanje uspjelo — isporučite robu
cancelledDaPlaćanje poništeno od strane kupca
expiredDaPoveznica za plaćanje je istekla
errorDaTehnički kvar

Najbolje prakse za webhookove

  1. Uvijek provjerite putem API-ja — webhook podaci sadrže samo ID narudžbe, nikada status. SDK-ov verifyWebhook() to radi automatski.
  2. Vratite HTTP 200 za potvrdu primitka. Bilo koji drugi kod pokreće do 10 ponovnih pokušaja (svake 2 minute).
  3. Implementirajte rezervno anketiranje — za narudžbe starije od 10 minuta koje nisu dosegle konačni status, anketirajte getOrder() kao sigurnosnu mrežu.
  4. Budite idempotentni — možete primiti isti webhook više puta.

Testne kartice

Koristite ove kartice u Cost+ testnom načinu (sandbox web stranica):

KarticaBrojNapomene
Visa (uspjeh)4111 1111 1111 1111Bilo koji CVV
Mastercard (uspjeh)5544 3300 0003 7Bilo koji CVV
Visa (odbijena)4111 1111 1111 1105Do Not Honor
Visa (nedovoljna sredstva)4111 1111 1111 1151Insufficient Funds

Koristite bilo koji budući datum isteka i bilo koji 3-znamenkasti CVC.

Demo aplikacija

Docker-bazirana demo aplikacija uključena je u GitHub repozitoriju za testiranje potpunog tijeka plaćanja.

Podrška

Trebate pomoć? Obratite se našem timu za podršku na support@costplus.io.

On this page