PHP
Uradni PHP SDK za plačilni prehod Cost+
Uradni PHP SDK za plačilni prehod Cost+. Poenostavlja tok preusmeritve HPP (gostovane plačilne strani), HMAC podpisovanje koristnih podatkov in preverjanje webhook-ov.
Lastnosti
- Brez zunanjih odvisnosti — uporablja le vgrajene PHP razširitve (
curl,json,hash) - PHP 8.1+ z readonly lastnostmi, imenovanimi argumenti in strogimi tipi
- HMAC-SHA256 generiranje podpisov in preverjanje s konstantnim časom prek
hash_equals - Samodejno preslikavanje snake_case/camelCase med API-jem in SDK-jem
- Razčlenjevanje webhook-ov + preverjanje naročil na osnovi API-ja
- Testirano na PHP 8.1, 8.2 in 8.3
Zahteve
- PHP 8.1 ali novejši
- Razširitve:
curl,json(obe vključeni v standardni PHP) - Trgovski račun Cost+ — dashboard.costplus.io
Namestitev
composer require nopayn/sdkHitri začetek
1. Inicializirajte odjemalca
use NoPayn\NoPaynClient;
$nopayn = new NoPaynClient([
'apiKey' => 'your-api-key',
'merchantId' => 'your-project',
]);2. Ustvarite plačilo in preusmerite 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',
]);
// Preusmerite stranko
// $result['orderUrl'] → HPP (stranka izbere plačilno metodo)
// $result['paymentUrl'] → neposredna povezava do plačilne metode prve transakcije
// $result['signature'] → HMAC-SHA256 za preverjanje
// $result['orderId'] → NoPayn UUID naročila
header('Location: ' . ($result['paymentUrl'] ?? $result['orderUrl']));3. Obdelajte 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') {
// Izpolnite naročilo
}
http_response_code(200);API referenca
new NoPaynClient(array $config)
| Parameter | Tip | Obvezno | Privzeto |
|---|---|---|---|
apiKey | string | Da | — |
merchantId | string | Da | — |
baseUrl | string | Ne | https://api.nopayn.co.uk |
$client->createOrder(array $params): array
Ustvari naročilo prek POST /v1/orders/.
| Parameter | Tip | Obvezno | Opis |
|---|---|---|---|
amount | int | ja | Znesek v manjši enoti ISO 4217 valute (na primer centi za EUR) |
currency | string | Da | Koda ISO 4217 (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | string | Ne | Vaša interna referenca naročila |
description | string | Ne | Opis naročila |
returnUrl | string | Ne | Preusmeritev po uspešnem plačilu |
failureUrl | string | Ne | Preusmeritev ob preklicu/poteku/napaki |
webhookUrl | string | Ne | Asinhrona obvestila o spremembi statusa |
locale | string | Ne | Jezik HPP (en-GB, de-DE, nl-NL itd.) |
paymentMethods | string[] | Ne | Filtriraj metode HPP |
expirationPeriod | string | Ne | Trajanje ISO 8601 (PT30M) |
Razpoložljive plačilne metode: credit-card, apple-pay, google-pay, vipps-mobilepay
$client->getOrder(string $orderId): array
Pridobi podrobnosti naročila prek GET /v1/orders/{id}/.
$client->createRefund(string $orderId, int $amount, ?string $description = null): array
Izda celotno ali delno vračilo prek POST /v1/orders/{id}/refunds/.
$client->generatePaymentUrl(array $params): array
Priročna metoda, ki ustvari naročilo in vrne:
[
'orderId' => string, // NoPayn UUID naročila
'orderUrl' => string, // HPP URL
'paymentUrl' => ?string, // Neposredni plačilni URL (prva transakcija)
'signature' => string, // HMAC-SHA256 od amount:currency:orderId
'order' => array, // Celoten objekt naročila
]$client->generateSignature(int $amount, string $currency, string $orderId): string
Generira HMAC-SHA256 šestnajstiški podpis.
$client->verifySignature(int $amount, string $currency, string $orderId, string $signature): bool
Preverjanje HMAC-SHA256 podpisa s konstantnim časom.
$client->verifyWebhook(string $rawBody): array
Razčleni telo webhook-a, nato pokliče GET /v1/orders/{id}/ za preverjanje dejanskega statusa.
Samostojne HMAC pripomočke
use NoPayn\Signature;
$sig = Signature::generate('your-api-key', 1295, 'EUR', 'order-uuid');
$ok = Signature::verify('your-api-key', 1295, 'EUR', 'order-uuid', $sig);Obravnava napak
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 naročil
| Status | Končni? | Opis |
|---|---|---|
new | Ne | Naročilo ustvarjeno |
processing | Ne | Plačilo v teku |
completed | Da | Plačilo uspešno — dostavite blago |
cancelled | Da | Plačilo preklicano s strani stranke |
expired | Da | Plačilna povezava je potekla |
error | Da | Tehnična napaka |
Najboljše prakse za webhook-e
- Vedno preverite prek API-ja — koristni podatki webhook-a vsebujejo samo ID naročila, nikoli statusa. SDK-jev
verifyWebhook()to naredi samodejno. - Vrnite HTTP 200 za potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
- Implementirajte rezervno poizvedovanje — za naročila, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte
getOrder()kot varnostno mrežo. - Bodite idempotentni — isti webhook lahko prejmete večkrat.
Testne kartice
Uporabite te kartice v testnem načinu Cost+ (spletno mesto peskovnika):
| Kartica | Številka | Opombe |
|---|---|---|
| Visa (uspeh) | 4111 1111 1111 1111 | Katerikoli CVV |
| Mastercard (uspeh) | 5544 3300 0003 7 | Katerikoli CVV |
| Visa (zavrnjena) | 4111 1111 1111 1105 | Zavrnitev |
| Visa (nezadostna sredstva) | 4111 1111 1111 1151 | Nezadostna sredstva |
Uporabite katerikoli prihodnji datum veljavnosti in katerokoli 3-mestno CVC kodo.
Predstavitvena aplikacija
Predstavitvena aplikacija na osnovi Docker je vključena v GitHub repozitorij za testiranje celotnega plačilnega toka.
Podpora
Potrebujete pomoč? Obrnite se na našo ekipo za podporo na support@costplus.io.