PHP

Επίσημο PHP SDK για την πύλη πληρωμών Cost+. Απλοποιεί τη ροή ανακατεύθυνσης HPP (Φιλοξενούμενη Σελίδα Πληρωμής), την υπογραφή HMAC payload και την επαλήθευση webhook.

Χαρακτηριστικά

Μηδέν εξωτερικές εξαρτήσεις — uses only built-in PHP extensions (curl, json, hash)
PHP 8.1+ with readonly properties, named arguments, and strict types
HMAC-SHA256 signature generation and constant-time verification via hash_equals
Automatic snake_case/camelCase mapping between the API and the SDK
Webhook parsing + API-based order verification
Tested across PHP 8.1, 8.2, and 8.3

Απαιτήσεις

PHP 8.1 or later
Extensions: curl, json (both included in standard PHP)
Λογαριασμός εμπόρου Cost+ — dashboard.costplus.io

Εγκατάσταση

composer require nopayn/sdk

Γρήγορη Εκκίνηση

1. Αρχικοποίηση του Client

use NoPayn\NoPaynClient;

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

2. Δημιουργία Πληρωμής και Ανακατεύθυνση στο 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. Διαχείριση του 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

`new NoPaynClient(array $config)`

Παράμετρος	Τύπος	Απαιτούμενη	Προεπιλογή
`apiKey`	`string`	Ναι	—
`merchantId`	`string`	Ναι	—
`baseUrl`	`string`	Όχι	`https://api.nopayn.co.uk`

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

Δημιουργεί παραγγελία μέσω POST /v1/orders/.

Παράμετρος	Τύπος	Απαιτούμενη	Περιγραφή
`amount`	`int`	Ναι	Ποσό στη μικρότερη μονάδα νομίσματος (λεπτά)
`currency`	`string`	Ναι	ISO 4217 code (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Όχι	Η εσωτερική αναφορά παραγγελίας σας
`description`	`string`	Όχι	Περιγραφή παραγγελίας
`returnUrl`	`string`	Όχι	Ανακατεύθυνση μετά από επιτυχή πληρωμή
`failureUrl`	`string`	Όχι	Ανακατεύθυνση σε ακύρωση/λήξη/σφάλμα
`webhookUrl`	`string`	Όχι	Ασύγχρονες ειδοποιήσεις αλλαγής κατάστασης
`locale`	`string`	Όχι	HPP language (`en-GB`, `de-DE`, `nl-NL`, etc.)
`paymentMethods`	`string[]`	Όχι	Φιλτράρισμα μεθόδων HPP
`expirationPeriod`	`string`	Όχι	ISO 8601 duration (`PT30M`)

Διαθέσιμες μέθοδοι πληρωμής: credit-card, apple-pay, google-pay, vipps-mobilepay

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

Ανακτά λεπτομέρειες παραγγελίας μέσω GET /v1/orders/{id}/.

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

Εκδίδει πλήρη ή μερική επιστροφή χρημάτων μέσω POST /v1/orders/{id}/refunds/.

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

Μέθοδος ευκολίας που δημιουργεί παραγγελία και επιστρέφει:

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

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

Επαλήθευση σταθερού χρόνου υπογραφής HMAC-SHA256.

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

Αναλύει το σώμα webhook, στη συνέχεια καλεί GET /v1/orders/{id}/ για επαλήθευση πραγματικής κατάστασης.

Αυτόνομα Εργαλεία HMAC

use NoPayn\Signature;

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

Διαχείριση Σφαλμάτων

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
}

Καταστάσεις Παραγγελίας

Κατάσταση	Τελική;	Περιγραφή
`new`	Όχι	Η παραγγελία δημιουργήθηκε
`processing`	Όχι	Πληρωμή σε εξέλιξη
`completed`	Ναι	Η πληρωμή ήταν επιτυχής — παραδώστε τα αγαθά
`cancelled`	Ναι	Η πληρωμή ακυρώθηκε από τον πελάτη
`expired`	Ναι	Ο σύνδεσμος πληρωμής έληξε
`error`	Ναι	Τεχνική αποτυχία

Βέλτιστες Πρακτικές Webhook

Πάντα επαληθεύετε μέσω API — το payload webhook περιέχει μόνο το αναγνωριστικό παραγγελίας, ποτέ την κατάσταση. Η μέθοδος verifyWebhook() του SDK το κάνει αυτόματα.
Επιστρέψτε HTTP 200 για επιβεβαίωση λήψης. Οποιοσδήποτε άλλος κωδικός ενεργοποιεί έως 10 επαναπροσπάθειες (2 λεπτά μεταξύ τους).
Υλοποιήστε εφεδρικό poller — για παραγγελίες παλαιότερες από 10 λεπτά που δεν έχουν φτάσει σε τελική κατάσταση, κάντε polling getOrder() ως δίχτυ ασφαλείας.
Να είστε idempotent — μπορεί να λάβετε το ίδιο webhook πολλές φορές.

Δοκιμαστικές Κάρτες

Χρησιμοποιήστε αυτές τις κάρτες στη δοκιμαστική λειτουργία Cost+ (ιστοσελίδα sandbox):

Κάρτα	Αριθμός	Σημειώσεις
Visa (επιτυχία)	`4111 1111 1111 1111`	Οποιοδήποτε CVV
Mastercard (επιτυχία)	`5544 3300 0003 7`	Οποιοδήποτε CVV
Visa (απόρριψη)	`4111 1111 1111 1105`	Do Not Honor
Visa (ανεπαρκές υπόλοιπο)	`4111 1111 1111 1151`	Insufficient Funds

Χρησιμοποιήστε οποιαδήποτε μελλοντική ημερομηνία λήξης και οποιοδήποτε 3ψήφιο CVC.

Εφαρμογή Επίδειξης

Μια εφαρμογή επίδειξης βασισμένη σε Docker περιλαμβάνεται στο GitHub repository για δοκιμή πλήρους ροής πληρωμής.

Υποστήριξη

Χρειάζεστε βοήθεια; Επικοινωνήστε με την ομάδα υποστήριξης στο support@costplus.io.

On this page