PHP

Hivatalos PHP SDK a Cost+ fizetési átjáróhoz. Egyszerűsíti a HPP (tárolt fizetési oldal) átirányítási folyamatot, a HMAC adatcsomag-aláírást és a webhook ellenőrzést.

Funkciók

Nulla külső függőség — csak beépített PHP kiterjesztéseket használ (curl, json, hash)
PHP 8.1+ readonly tulajdonságokkal, nevesített argumentumokkal és szigorú típusokkal
HMAC-SHA256 aláírás generálás és állandó idejű ellenőrzés hash_equals segítségével
Automatikus snake_case/camelCase leképezés az API és az SDK között
Webhook feldolgozás + API-alapú rendelés ellenőrzés
Tesztelve PHP 8.1, 8.2 és 8.3 verziókkal

Követelmények

PHP 8.1 vagy újabb
Kiterjesztések: curl, json (mindkettő a standard PHP részét képezi)
Cost+ kereskedői fiók — dashboard.costplus.io

Telepítés

composer require nopayn/sdk

Gyorsindítás

1. A kliens inicializálása

use NoPayn\NoPaynClient;

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

2. Fizetés létrehozása és átirányítás a HPP-re

$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. Webhook kezelése

$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-referencia

`new NoPaynClient(array $config)`

Paraméter	Típus	Kötelező	Alapértelmezett
`apiKey`	`string`	Igen	—
`merchantId`	`string`	Igen	—
`baseUrl`	`string`	Nem	`https://api.nopayn.co.uk`

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

Rendelést hoz létre a POST /v1/orders/ végponton.

Paraméter	Típus	Kötelező	Leírás
`amount`	`int`	Igen	Összeg a legkisebb pénznem-egységben (cent)
`currency`	`string`	Igen	ISO 4217 kód (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nem	Az Ön belső rendelési hivatkozása
`description`	`string`	Nem	Rendelés leírása
`returnUrl`	`string`	Nem	Átirányítás sikeres fizetés után
`failureUrl`	`string`	Nem	Átirányítás törlés/lejárat/hiba esetén
`webhookUrl`	`string`	Nem	Aszinkron állapotváltozási értesítések
`locale`	`string`	Nem	HPP nyelv (`en-GB`, `de-DE`, `nl-NL` stb.)
`paymentMethods`	`string[]`	Nem	HPP módok szűrése
`expirationPeriod`	`string`	Nem	ISO 8601 időtartam (`PT30M`)

Elérhető fizetési módok: credit-card, apple-pay, google-pay, vipps-mobilepay

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

Rendelés részleteinek lekérdezése a GET /v1/orders/{id}/ végponton.

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

Teljes vagy részleges visszatérítés kiadása a POST /v1/orders/{id}/refunds/ végponton.

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

Kényelmi metódus, amely rendelést hoz létre és visszaadja:

[
    '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`

HMAC-SHA256 hex aláírást generál.

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

HMAC-SHA256 aláírás állandó idejű ellenőrzése.

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

Feldolgozza a webhook törzset, majd meghívja a GET /v1/orders/{id}/ végpontot az aktuális állapot ellenőrzéséhez.

Önálló HMAC segédeszközök

use NoPayn\Signature;

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

Hibakezelés

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
}

Rendelés állapotok

Állapot	Végleges?	Leírás
`new`	Nem	Rendelés létrehozva
`processing`	Nem	Fizetés folyamatban
`completed`	Igen	Fizetés sikeres — szállítsa az árut
`cancelled`	Igen	Fizetés törölve az ügyfél által
`expired`	Igen	A fizetési link lejárt
`error`	Igen	Technikai hiba

Webhook bevált gyakorlatok

Mindig ellenőrizze az API-n keresztül — a webhook adatcsomag csak a rendelés azonosítóját tartalmazza, soha nem az állapotot. Az SDK verifyWebhook() metódusa ezt automatikusan elvégzi.
Válaszoljon HTTP 200-zal a fogadás nyugtázásához. Bármely más kód legfeljebb 10 újrapróbálkozást vált ki (2 percenként).
Alkalmazzon tartalék lekérdezést — a 10 percnél régebbi, végleges állapotot még el nem ért rendelésekhez kérdezze le a getOrder() metódust biztonsági hálóként.
Legyen idempotens — ugyanazt a webhookot többször is megkaphatja.

Tesztkártyák

Használja ezeket a kártyákat Cost+ teszt módban (sandbox weboldal):

Kártya	Szám	Megjegyzés
Visa (sikeres)	`4111 1111 1111 1111`	Bármely CVV
Mastercard (sikeres)	`5544 3300 0003 7`	Bármely CVV
Visa (elutasítva)	`4111 1111 1111 1105`	Do Not Honor
Visa (elégtelen fedezet)	`4111 1111 1111 1151`	Insufficient Funds

Használjon bármely jövőbeli lejárati dátumot és bármely 3 számjegyű CVC-t.

Demo alkalmazás

Egy Docker-alapú demo alkalmazás található a GitHub tárolóban a teljes fizetési folyamat teszteléséhez.

Támogatás

Segítségre van szüksége? Forduljon ügyfélszolgálatunkhoz: support@costplus.io.

On this page