PHP

Offizielles PHP SDK für das Cost+ Zahlungsgateway. Vereinfacht den HPP (Hosted Payment Page) Weiterleitungsablauf, die HMAC-Payload-Signierung und die Webhook-Verifizierung.

Funktionen

Keine externen Abhängigkeiten — verwendet nur integrierte PHP-Erweiterungen (curl, json, hash)
PHP 8.1+ mit Readonly-Properties, Named Arguments und Strict Types
HMAC-SHA256-Signaturgenerierung und zeitkonstante Verifizierung über hash_equals
Automatisches snake_case/camelCase-Mapping zwischen API und SDK
Webhook-Parsing + API-basierte Bestellungsverifizierung
Getestet mit PHP 8.1, 8.2 und 8.3

Voraussetzungen

PHP 8.1 oder neuer
Erweiterungen: curl, json (beide im Standard-PHP enthalten)
Ein Cost+ Händlerkonto — dashboard.costplus.io

Installation

composer require nopayn/sdk

Schnellstart

1. Client initialisieren

use NoPayn\NoPaynClient;

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

2. Zahlung erstellen und zur HPP weiterleiten

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

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

`new NoPaynClient(array $config)`

Parameter	Typ	Erforderlich	Standard
`apiKey`	`string`	Ja	—
`merchantId`	`string`	Ja	—
`baseUrl`	`string`	Nein	`https://api.nopayn.co.uk`

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

Erstellt eine Bestellung über POST /v1/orders/.

Parameter	Typ	Erforderlich	Beschreibung
`amount`	`int`	Ja	Betrag in kleinster Währungseinheit (Cent)
`currency`	`string`	Ja	ISO 4217 Code (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nein	Ihre interne Bestellreferenz
`description`	`string`	Nein	Bestellbeschreibung
`returnUrl`	`string`	Nein	Weiterleitung nach erfolgreicher Zahlung
`failureUrl`	`string`	Nein	Weiterleitung bei Abbruch/Ablauf/Fehler
`webhookUrl`	`string`	Nein	Asynchrone Statusänderungs-Benachrichtigungen
`locale`	`string`	Nein	HPP-Sprache (`en-GB`, `de-DE`, `nl-NL` usw.)
`paymentMethods`	`string[]`	Nein	HPP-Methoden filtern
`expirationPeriod`	`string`	Nein	ISO 8601 Dauer (`PT30M`)

Verfügbare Zahlungsmethoden: credit-card, apple-pay, google-pay, vipps-mobilepay

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

Ruft Bestellungsdetails über GET /v1/orders/{id}/ ab.

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

Stellt eine vollständige oder teilweise Erstattung über POST /v1/orders/{id}/refunds/ aus.

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

Komfortmethode, die eine Bestellung erstellt und zurückgibt:

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

Generiert eine HMAC-SHA256-Hex-Signatur.

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

Zeitkonstante Verifizierung einer HMAC-SHA256-Signatur.

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

Parst den Webhook-Body und ruft dann GET /v1/orders/{id}/ auf, um den tatsächlichen Status zu verifizieren.

Eigenständige HMAC-Hilfsfunktionen

use NoPayn\Signature;

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

Fehlerbehandlung

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
}

Bestellungsstatus

Status	Endgültig?	Beschreibung
`new`	Nein	Bestellung erstellt
`processing`	Nein	Zahlung in Bearbeitung
`completed`	Ja	Zahlung erfolgreich — Ware liefern
`cancelled`	Ja	Zahlung vom Kunden storniert
`expired`	Ja	Zahlungslink abgelaufen
`error`	Ja	Technischer Fehler

Webhook Best Practices

Immer über die API verifizieren — der Webhook-Payload enthält nur die Bestell-ID, niemals den Status. Die verifyWebhook()-Methode des SDK erledigt dies automatisch.
HTTP 200 zurückgeben, um den Empfang zu bestätigen. Jeder andere Code löst bis zu 10 Wiederholungsversuche aus (im 2-Minuten-Abstand).
Backup-Poller implementieren — für Bestellungen, die älter als 10 Minuten sind und noch keinen Endstatus erreicht haben, getOrder() als Sicherheitsnetz abfragen.
Idempotent sein — Sie können denselben Webhook mehrfach erhalten.

Testkarten

Verwenden Sie diese Karten im Cost+ Testmodus (Sandbox-Website):

Karte	Nummer	Hinweise
Visa (Erfolg)	`4111 1111 1111 1111`	Beliebiger CVV
Mastercard (Erfolg)	`5544 3300 0003 7`	Beliebiger CVV
Visa (abgelehnt)	`4111 1111 1111 1105`	Do Not Honor
Visa (unzureichendes Guthaben)	`4111 1111 1111 1151`	Insufficient Funds

Verwenden Sie ein beliebiges zukünftiges Ablaufdatum und eine beliebige 3-stellige CVC.

Demo-App

Eine Docker-basierte Demo-App ist im GitHub-Repository enthalten, um den vollständigen Zahlungsablauf zu testen.

Support

Brauchen Sie Hilfe? Kontaktieren Sie unser Support-Team unter support@costplus.io.

On this page