PHP

SDK oficial PHP pentru gateway-ul de plăți Cost+. Simplifică fluxul de redirecționare HPP (pagina de plată găzduită), semnarea HMAC a payload-ului și verificarea webhook-urilor.

Funcționalități

Zero dependențe externe — folosește doar extensii PHP integrate (curl, json, hash)
PHP 8.1+ cu proprietăți readonly, argumente denumite și tipuri stricte
Generare semnătură HMAC-SHA256 și verificare cu timp constant prin hash_equals
Mapare automată snake_case/camelCase între API și SDK
Parsare webhook + verificare comenzi bazată pe API
Testat pe PHP 8.1, 8.2 și 8.3

Cerințe

PHP 8.1 sau mai nou
Extensii: curl, json (ambele incluse în PHP standard)
Un cont de comerciant Cost+ — dashboard.costplus.io

Instalare

composer require nopayn/sdk

Pornire rapidă

1. Inițializați clientul

use NoPayn\NoPaynClient;

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

2. Creați o plată și redirecționați către 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. Gestionați webhook-ul

$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);

Referință API

`new NoPaynClient(array $config)`

Parametru	Tip	Obligatoriu	Implicit
`apiKey`	`string`	Da	—
`merchantId`	`string`	Da	—
`baseUrl`	`string`	Nu	`https://api.nopayn.co.uk`

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

Creează o comandă prin POST /v1/orders/.

Parametru	Tip	Obligatoriu	Descriere
`amount`	`int`	Da	Suma în cea mai mică unitate monetară (cenți)
`currency`	`string`	Da	Cod ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nu	Referința dvs. internă de comandă
`description`	`string`	Nu	Descrierea comenzii
`returnUrl`	`string`	Nu	Redirecționare după plata reușită
`failureUrl`	`string`	Nu	Redirecționare la anulare/expirare/eroare
`webhookUrl`	`string`	Nu	Notificări asincrone de schimbare status
`locale`	`string`	Nu	Limba HPP (`en-GB`, `de-DE`, `nl-NL`, etc.)
`paymentMethods`	`string[]`	Nu	Filtrare metode HPP
`expirationPeriod`	`string`	Nu	Durată ISO 8601 (`PT30M`)

Metode de plată disponibile: credit-card, apple-pay, google-pay, vipps-mobilepay

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

Preia detaliile comenzii prin GET /v1/orders/{id}/.

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

Emite o rambursare totală sau parțială prin POST /v1/orders/{id}/refunds/.

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

Metodă de convenință care creează o comandă și returnează:

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

Generează o semnătură hex HMAC-SHA256.

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

Verificare cu timp constant a unei semnături HMAC-SHA256.

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

Parsează corpul webhook-ului, apoi apelează GET /v1/orders/{id}/ pentru a verifica statusul real.

Utilitare HMAC independente

use NoPayn\Signature;

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

Gestionarea erorilor

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
}

Statusuri comandă

Status	Final?	Descriere
`new`	Nu	Comandă creată
`processing`	Nu	Plată în curs
`completed`	Da	Plată reușită — livrați marfa
`cancelled`	Da	Plată anulată de client
`expired`	Da	Linkul de plată a expirat
`error`	Da	Eroare tehnică

Bune practici pentru webhook-uri

Verificați întotdeauna prin API — payload-ul webhook conține doar ID-ul comenzii, niciodată statusul. Metoda verifyWebhook() a SDK-ului face acest lucru automat.
Returnați HTTP 200 pentru a confirma recepția. Orice alt cod declanșează până la 10 reîncercări (la 2 minute distanță).
Implementați un poller de rezervă — pentru comenzile mai vechi de 10 minute care nu au ajuns la un status final, interogați getOrder() ca rețea de siguranță.
Fiți idempotent — puteți primi același webhook de mai multe ori.

Carduri de test

Folosiți aceste carduri în modul de test Cost+ (site web sandbox):

Card	Număr	Note
Visa (succes)	`4111 1111 1111 1111`	Orice CVV
Mastercard (succes)	`5544 3300 0003 7`	Orice CVV
Visa (refuzat)	`4111 1111 1111 1105`	Do Not Honor
Visa (fonduri insuficiente)	`4111 1111 1111 1151`	Insufficient Funds

Folosiți orice dată de expirare viitoare și orice CVC de 3 cifre.

Aplicație demo

O aplicație demo bazată pe Docker este inclusă în depozitul GitHub pentru testarea fluxului complet de plată.

Suport

Aveți nevoie de ajutor? Contactați echipa noastră de suport la support@costplus.io.

On this page