Cost+Docs

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/sdk

Bidu 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)

ParametruTipMeħtieġDefault
apiKeystringIva—
merchantIdstringIva—
baseUrlstringLehttps://api.nopayn.co.uk

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

Joħloq ordni permezz ta' POST /v1/orders/.

ParametruTipMeħtieġDeskrizzjoni
amountintIvaAmmont fl-unità minuri ISO 4217 tal-munita (per eżempju, ċenteżmi għal EUR)
currencystringIvaKodiċi ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchantOrderIdstringLeIr-referenza interna tal-ordni tiegħek
descriptionstringLeDeskrizzjoni tal-ordni
returnUrlstringLeRedirect wara ħlas li rnexxielu
failureUrlstringLeRedirect fuq kanċellazzjoni/skadenza/żball
webhookUrlstringLeNotifiki asinkroni ta' bidla fl-istatus
localestringLeLingwa tal-HPP (en-GB, de-DE, nl-NL, eċċ.)
paymentMethodsstring[]LeIffiltra l-metodi tal-HPP
expirationPeriodstringLeTul 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

StatusFinali?Deskrizzjoni
newLeOrdni maħluqa
processingLeĦlas qed isir
completedIvaĦlas irnexxielu — ikkonsenja l-prodotti
cancelledIvaĦlas ikkanċellat mill-klijent
expiredIvaLink tal-ħlas skada
errorIvaFalliment tekniku

L-Aħjar Prattiċi għall-Webhooks

  1. 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.
  2. Irritorna HTTP 200 biex tikkonferma r-riċevuta. Kwalunkwe kodiċi ieħor jiskatta sa 10 retries (2 minuti bejn xulxin).
  3. 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à.
  4. 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):

KartaNumruNoti
Visa (suċċess)4111 1111 1111 1111Kwalunkwe CVV
Mastercard (suċċess)5544 3300 0003 7Kwalunkwe CVV
Visa (miċħuda)4111 1111 1111 1105Do Not Honor
Visa (fondi insuffiċjenti)4111 1111 1111 1151Insufficient 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.

On this page