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/sdkBrzi 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)
| Parametar | Tip | Obavezno | Zadano |
|---|---|---|---|
apiKey | string | Da | — |
merchantId | string | Da | — |
baseUrl | string | Ne | https://api.nopayn.co.uk |
$client->createOrder(array $params): array
Stvara narudžbu putem POST /v1/orders/.
| Parametar | Tip | Obavezno | Opis |
|---|---|---|---|
amount | int | Da | Iznos u manjoj jedinici ISO 4217 valute (na primjer, centi za EUR) |
currency | string | Da | ISO 4217 kod (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | string | Ne | Vaša interna referenca narudžbe |
description | string | Ne | Opis narudžbe |
returnUrl | string | Ne | Preusmjeravanje nakon uspješnog plaćanja |
failureUrl | string | Ne | Preusmjeravanje pri poništenju/isteku/grešci |
webhookUrl | string | Ne | Asinkrone obavijesti o promjeni statusa |
locale | string | Ne | Jezik HPP-a (en-GB, de-DE, nl-NL itd.) |
paymentMethods | string[] | Ne | Filtriranje HPP načina |
expirationPeriod | string | Ne | ISO 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
| Status | Konačan? | Opis |
|---|---|---|
new | Ne | Narudžba stvorena |
processing | Ne | Plaćanje u tijeku |
completed | Da | Plaćanje uspjelo — isporučite robu |
cancelled | Da | Plaćanje poništeno od strane kupca |
expired | Da | Poveznica za plaćanje je istekla |
error | Da | Tehnički kvar |
Najbolje prakse za webhookove
- Uvijek provjerite putem API-ja — webhook podaci sadrže samo ID narudžbe, nikada status. SDK-ov
verifyWebhook()to radi automatski. - Vratite HTTP 200 za potvrdu primitka. Bilo koji drugi kod pokreće do 10 ponovnih pokušaja (svake 2 minute).
- Implementirajte rezervno anketiranje — za narudžbe starije od 10 minuta koje nisu dosegle konačni status, anketirajte
getOrder()kao sigurnosnu mrežu. - Budite idempotentni — možete primiti isti webhook više puta.
Testne kartice
Koristite ove kartice u Cost+ testnom načinu (sandbox web stranica):
| Kartica | Broj | Napomene |
|---|---|---|
| Visa (uspjeh) | 4111 1111 1111 1111 | Bilo koji CVV |
| Mastercard (uspjeh) | 5544 3300 0003 7 | Bilo koji CVV |
| Visa (odbijena) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedovoljna sredstva) | 4111 1111 1111 1151 | Insufficient 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.