PHP

Oficiālais PHP SDK Cost+ maksājumu vārtejai. Vienkāršo HPP (mitinātās maksājuma lapas) novirzīšanas plūsmu, HMAC datu parakstīšanu un webhook verifikāciju.

Funkcijas

Nulles ārējās atkarības — izmanto tikai iebūvētos PHP paplašinājumus (curl, json, hash)
PHP 8.1+ ar readonly īpašībām, nosauktiem argumentiem un stingriem tipiem
HMAC-SHA256 parakstu ģenerēšana un konstantā laika verifikācija caur hash_equals
Automātiska snake_case/camelCase kartēšana starp API un SDK
Webhook parsēšana + API bāzēta pasūtījuma verifikācija
Testēts PHP 8.1, 8.2 un 8.3

Prasības

PHP 8.1 vai jaunāka versija
Paplašinājumi: curl, json (abi iekļauti standarta PHP)
Cost+ tirgotāja konts — dashboard.costplus.io

Instalācija

composer require nopayn/sdk

Ātrais sākums

1. Inicializējiet klientu

use NoPayn\NoPaynClient;

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

2. Izveidojiet maksājumu un novirziet uz 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. Apstrādājiet 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 atsauce

`new NoPaynClient(array $config)`

Parametrs	Tips	Obligāts	Noklusējums
`apiKey`	`string`	Jā	—
`merchantId`	`string`	Jā	—
`baseUrl`	`string`	Nē	`https://api.nopayn.co.uk`

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

Izveido pasūtījumu caur POST /v1/orders/.

Parametrs	Tips	Obligāts	Apraksts
`amount`	`int`	Jā	Summa mazākajā valūtas vienībā (centos)
`currency`	`string`	Jā	ISO 4217 kods (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nē	Jūsu iekšējā pasūtījuma atsauce
`description`	`string`	Nē	Pasūtījuma apraksts
`returnUrl`	`string`	Nē	Novirzīšana pēc veiksmīga maksājuma
`failureUrl`	`string`	Nē	Novirzīšana atcelšanas/termiņa beigšanās/kļūdas gadījumā
`webhookUrl`	`string`	Nē	Asinhroniem statusa izmaiņu paziņojumiem
`locale`	`string`	Nē	HPP valoda (`en-GB`, `de-DE`, `nl-NL` utt.)
`paymentMethods`	`string[]`	Nē	Filtrēt HPP metodes
`expirationPeriod`	`string`	Nē	ISO 8601 ilgums (`PT30M`)

Pieejamās maksājumu metodes: credit-card, apple-pay, google-pay, vipps-mobilepay

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

Iegūst pasūtījuma datus caur GET /v1/orders/{id}/.

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

Veic pilnu vai daļēju atmaksu caur POST /v1/orders/{id}/refunds/.

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

Ērtuma metode, kas izveido pasūtījumu un atgriež:

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

Ģenerē HMAC-SHA256 heksadecimālo parakstu.

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

Konstantā laika HMAC-SHA256 paraksta verifikācija.

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

Parsē webhook saturu, tad izsauc GET /v1/orders/{id}/, lai verificētu faktisko statusu.

Atsevišķās HMAC utilītas

use NoPayn\Signature;

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

Kļūdu apstrāde

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
}

Pasūtījumu statusi

Statuss	Galīgs?	Apraksts
`new`	Nē	Pasūtījums izveidots
`processing`	Nē	Maksājums procesā
`completed`	Jā	Maksājums veiksmīgs — piegādājiet preci
`cancelled`	Jā	Maksājums atcelts klienta
`expired`	Jā	Maksājuma saites termiņš beidzies
`error`	Jā	Tehniska kļūme

Webhook labākā prakse

Vienmēr verificējiet caur API — webhook saturs satur tikai pasūtījuma ID, nekad statusu. SDK verifyWebhook() to dara automātiski.
Atgrieziet HTTP 200, lai apstiprinātu saņemšanu. Jebkurš cits kods izsauc līdz 10 atkārtojumiem (2 minūtes starpā).
Ieviesiet rezerves aptaujātāju — pasūtījumiem, kas vecāki par 10 minūtēm un nav sasnieguši galīgo statusu, aptaujājiet getOrder() kā drošības tīklu.
Esiet idempotents — jūs varat saņemt vienu un to pašu webhook vairākas reizes.

Testa kartes

Izmantojiet šīs kartes Cost+ testa režīmā (sandbox vietne):

Karte	Numurs	Piezīmes
Visa (veiksmīgs)	`4111 1111 1111 1111`	Jebkurš CVV
Mastercard (veiksmīgs)	`5544 3300 0003 7`	Jebkurš CVV
Visa (noraidīts)	`4111 1111 1111 1105`	Do Not Honor
Visa (nepietiekami līdzekļi)	`4111 1111 1111 1151`	Insufficient Funds

Izmantojiet jebkuru nākotnes derīguma termiņu un jebkuru 3 ciparu CVC.

Demo lietotne

Docker bāzēta demo lietotne ir iekļauta GitHub repozitorijā pilnas maksājumu plūsmas testēšanai.

Atbalsts

Nepieciešama palīdzība? Sazinieties ar mūsu atbalsta komandu: support@costplus.io.

On this page