Cost+Docs

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

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

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

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

Ustvari naročilo prek POST /v1/orders/.

ParameterTipObveznoOpis
amountintjaZnesek v manjši enoti ISO 4217 valute (na primer centi za EUR)
currencystringDaKoda ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchantOrderIdstringNeVaša interna referenca naročila
descriptionstringNeOpis naročila
returnUrlstringNePreusmeritev po uspešnem plačilu
failureUrlstringNePreusmeritev ob preklicu/poteku/napaki
webhookUrlstringNeAsinhrona obvestila o spremembi statusa
localestringNeJezik HPP (en-GB, de-DE, nl-NL itd.)
paymentMethodsstring[]NeFiltriraj metode HPP
expirationPeriodstringNeTrajanje 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

StatusKončni?Opis
newNeNaročilo ustvarjeno
processingNePlačilo v teku
completedDaPlačilo uspešno — dostavite blago
cancelledDaPlačilo preklicano s strani stranke
expiredDaPlačilna povezava je potekla
errorDaTehnična napaka

Najboljše prakse za webhook-e

  1. Vedno preverite prek API-ja — koristni podatki webhook-a vsebujejo samo ID naročila, nikoli statusa. SDK-jev verifyWebhook() to naredi samodejno.
  2. Vrnite HTTP 200 za potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
  3. Implementirajte rezervno poizvedovanje — za naročila, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte getOrder() kot varnostno mrežo.
  4. Bodite idempotentni — isti webhook lahko prejmete večkrat.

Testne kartice

Uporabite te kartice v testnem načinu Cost+ (spletno mesto peskovnika):

KarticaŠtevilkaOpombe
Visa (uspeh)4111 1111 1111 1111Katerikoli CVV
Mastercard (uspeh)5544 3300 0003 7Katerikoli CVV
Visa (zavrnjena)4111 1111 1111 1105Zavrnitev
Visa (nezadostna sredstva)4111 1111 1111 1151Nezadostna 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.

On this page