PHP
SDK uffiċjali ta' PHP għall-gateway tal-ħlas Cost+
SDK uffiċjali ta' PHP għall-gateway tal-ħlas Cost+. Jissimplifika l-flusso ta' redirect tal-HPP (Paġna ta' Ħlas Ospitata), il-firma tal-payload HMAC, u l-verifika tal-webhooks.
Karatteristiċi
- Żero dipendenzi esterni — juża biss estensjonijiet integrati ta' PHP (
curl,json,hash) - PHP 8.1+ b'readonly properties, named arguments, u strict types
- Ġenerazzjoni ta' firma HMAC-SHA256 u verifika b'ħin kostanti permezz ta'
hash_equals - Mappa awtomatika ta' snake_case/camelCase bejn l-API u l-SDK
- Ipparsjar tal-webhooks + verifika tal-ordni bbażata fuq l-API
- Ittestjat fuq PHP 8.1, 8.2, u 8.3
Rekwiżiti
- PHP 8.1 jew aktar tard
- Estensjonijiet:
curl,json(it-tnejn inklużi f'PHP standard) - Kont ta' kummerċjant Cost+ — dashboard.costplus.io
Installazzjoni
composer require nopayn/sdkBidu Malajr
1. Inizjalizza l-Klijent
use NoPayn\NoPaynClient;
$nopayn = new NoPaynClient([
'apiKey' => 'your-api-key',
'merchantId' => 'your-project',
]);2. Oħloq Ħlas u Irridirezzjona lejn il-HPP
$result = $nopayn->generatePaymentUrl([
'amount' => 1295, // €12.95 f'ċenteżmi
'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',
]);
// Irridirezzjona l-klijent
// $result['orderUrl'] → HPP (il-klijent jagħżel il-metodu ta' ħlas)
// $result['paymentUrl'] → link dirett lejn il-metodu ta' ħlas tal-ewwel tranżazzjoni
// $result['signature'] → HMAC-SHA256 għall-verifika
// $result['orderId'] → UUID tal-ordni NoPayn
header('Location: ' . ($result['paymentUrl'] ?? $result['orderUrl']));3. Ittratta l-Webhook
$rawBody = file_get_contents('php://input');
$verified = $nopayn->verifyWebhook($rawBody);
echo $verified['order']['status']; // 'completed', 'cancelled', eċċ.
echo $verified['isFinal']; // true meta l-ordni ma tinbidilx aktar
if ($verified['order']['status'] === 'completed') {
// Issodisfa l-ordni
}
http_response_code(200);Referenza tal-API
new NoPaynClient(array $config)
| Parametru | Tip | Meħtieġ | Default |
|---|---|---|---|
apiKey | string | Iva | — |
merchantId | string | Iva | — |
baseUrl | string | Le | https://api.nopayn.co.uk |
$client->createOrder(array $params): array
Joħloq ordni permezz ta' POST /v1/orders/.
| Parametru | Tip | Meħtieġ | Deskrizzjoni |
|---|---|---|---|
amount | int | Iva | Ammont fl-unità minuri ISO 4217 tal-munita (per eżempju, ċenteżmi għal EUR) |
currency | string | Iva | Kodiċi ISO 4217 (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | string | Le | Ir-referenza interna tal-ordni tiegħek |
description | string | Le | Deskrizzjoni tal-ordni |
returnUrl | string | Le | Redirect wara ħlas li rnexxielu |
failureUrl | string | Le | Redirect fuq kanċellazzjoni/skadenza/żball |
webhookUrl | string | Le | Notifiki asinkroni ta' bidla fl-istatus |
locale | string | Le | Lingwa tal-HPP (en-GB, de-DE, nl-NL, eċċ.) |
paymentMethods | string[] | Le | Iffiltra l-metodi tal-HPP |
expirationPeriod | string | Le | Tul ta' żmien ISO 8601 (PT30M) |
Metodi ta' ħlas disponibbli: credit-card, apple-pay, google-pay, vipps-mobilepay
$client->getOrder(string $orderId): array
Jiġbed id-dettalji tal-ordni permezz ta' GET /v1/orders/{id}/.
$client->createRefund(string $orderId, int $amount, ?string $description = null): array
Joħroġ rifużjoni sħiħa jew parzjali permezz ta' POST /v1/orders/{id}/refunds/.
$client->generatePaymentUrl(array $params): array
Metodu ta' konvenjenza li joħloq ordni u jirritorna:
[
'orderId' => string, // UUID tal-ordni NoPayn
'orderUrl' => string, // URL tal-HPP
'paymentUrl' => ?string, // URL ta' ħlas dirett (l-ewwel tranżazzjoni)
'signature' => string, // HMAC-SHA256 ta' amount:currency:orderId
'order' => array, // Oġġett sħiħ tal-ordni
]$client->generateSignature(int $amount, string $currency, string $orderId): string
Jiġġenera firma HMAC-SHA256 hex.
$client->verifySignature(int $amount, string $currency, string $orderId, string $signature): bool
Verifika b'ħin kostanti ta' firma HMAC-SHA256.
$client->verifyWebhook(string $rawBody): array
Jipparsja l-korp tal-webhook, imbagħad isejjaħ GET /v1/orders/{id}/ biex jivverifika l-istatus attwali.
Utilitajiet HMAC Standalone
use NoPayn\Signature;
$sig = Signature::generate('your-api-key', 1295, 'EUR', 'order-uuid');
$ok = Signature::verify('your-api-key', 1295, 'EUR', 'order-uuid', $sig);Trattar tal-Żbalji
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, eċċ.
print_r($e->getErrorBody()); // Risposta ta' żball mhux ipproċessata tal-API
} catch (NoPaynException $e) {
echo $e->getMessage(); // Żball tan-network jew tal-ipparsjar
}Statuses tal-Ordni
| Status | Finali? | Deskrizzjoni |
|---|---|---|
new | Le | Ordni maħluqa |
processing | Le | Ħlas qed isir |
completed | Iva | Ħlas irnexxielu — ikkonsenja l-prodotti |
cancelled | Iva | Ħlas ikkanċellat mill-klijent |
expired | Iva | Link tal-ħlas skada |
error | Iva | Falliment tekniku |
L-Aħjar Prattiċi għall-Webhooks
- Dejjem ivverifika permezz tal-API — il-payload tal-webhook fih biss l-ID tal-ordni, qatt l-istatus. Il-
verifyWebhook()tal-SDK jagħmel dan awtomatikament. - Irritorna HTTP 200 biex tikkonferma r-riċevuta. Kwalunkwe kodiċi ieħor jiskatta sa 10 retries (2 minuti bejn xulxin).
- Implimenta backup poller — għal ordnijiet itqal minn 10 minuti li għadhom ma laħqux status finali, agħmel polling ta'
getOrder()bħala xibka ta' sigurtà. - Kun idempotenti — tista' tirċievi l-istess webhook aktar minn darba.
Karti tat-Test
Uża dawn il-karti f'modalità tat-test ta' Cost+ (website sandbox):
| Karta | Numru | Noti |
|---|---|---|
| Visa (suċċess) | 4111 1111 1111 1111 | Kwalunkwe CVV |
| Mastercard (suċċess) | 5544 3300 0003 7 | Kwalunkwe CVV |
| Visa (miċħuda) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (fondi insuffiċjenti) | 4111 1111 1111 1151 | Insufficient Funds |
Uża kwalunkwe data ta' skadenza futura u kwalunkwe CVC ta' 3 ċifri.
App Demo
App demo bbażata fuq Docker hija inkluża fir-repożitorju ta' GitHub għall-ittestjar tal-flusso sħiħ tal-ħlas.
Appoġġ
Għandek bżonn l-għajnuna? Ikkuntattja t-tim tal-appoġġ tagħna fuq support@costplus.io.