PHP

Virallinen PHP SDK Cost+-maksuportille. Yksinkertaistaa HPP (isännöidyn maksusivun) uudelleenohjausta, HMAC-allekirjoitusta ja webhook-vahvistusta.

Ominaisuudet

Nolla ulkoista riippuvuutta — käyttää vain PHP:n sisäänrakennettuja laajennuksia (curl, json, hash)
PHP 8.1+ readonly-ominaisuuksilla, nimetyillä argumenteilla ja tiukoilla tyypeillä
HMAC-SHA256-allekirjoituksen luonti ja vakioaikainen vahvistus hash_equals-funktiolla
Automaattinen snake_case/camelCase-muunnos API:n ja SDK:n välillä
Webhook-jäsennys + API-pohjainen tilauksen vahvistus
Testattu PHP 8.1-, 8.2- ja 8.3-versioilla

Vaatimukset

PHP 8.1 tai uudempi
Laajennukset: curl, json (molemmat sisältyvät PHP:n vakioasennukseen)
Cost+-kauppiastili — dashboard.costplus.io

Asennus

composer require nopayn/sdk

Pikaopas

1. Alusta asiakas

use NoPayn\NoPaynClient;

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

2. Luo maksu ja ohjaa HPP:hen

$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. Käsittele 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-viite

`new NoPaynClient(array $config)`

Parametri	Tyyppi	Pakollinen	Oletus
`apiKey`	`string`	Kyllä	—
`merchantId`	`string`	Kyllä	—
`baseUrl`	`string`	Ei	`https://api.nopayn.co.uk`

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

Luo tilauksen kutsulla POST /v1/orders/.

Parametri	Tyyppi	Pakollinen	Kuvaus
`amount`	`int`	Kyllä	Summa pienimmässä valuuttayksikössä (senteissä)
`currency`	`string`	Kyllä	ISO 4217 -koodi (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Ei	Oma sisäinen tilausviitteesi
`description`	`string`	Ei	Tilauksen kuvaus
`returnUrl`	`string`	Ei	Uudelleenohjaus onnistuneen maksun jälkeen
`failureUrl`	`string`	Ei	Uudelleenohjaus peruutuksen/vanhenemisen/virheen yhteydessä
`webhookUrl`	`string`	Ei	Asynkroniset tilanmuutosilmoitukset
`locale`	`string`	Ei	HPP:n kieli (`en-GB`, `de-DE`, `nl-NL` jne.)
`paymentMethods`	`string[]`	Ei	Suodata HPP:n maksutapoja
`expirationPeriod`	`string`	Ei	ISO 8601 -kesto (`PT30M`)

Käytettävissä olevat maksutavat: credit-card, apple-pay, google-pay, vipps-mobilepay

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

Hakee tilauksen tiedot kutsulla GET /v1/orders/{id}/.

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

Tekee täyden tai osittaisen palautuksen kutsulla POST /v1/orders/{id}/refunds/.

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

Apumetodi, joka luo tilauksen ja palauttaa:

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

Luo HMAC-SHA256 hex-allekirjoituksen.

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

Vakioaikainen HMAC-SHA256-allekirjoituksen vahvistus.

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

Jäsentää webhook-rungon ja kutsuu sitten GET /v1/orders/{id}/ varmistaakseen todellisen tilan.

Erilliset HMAC-apufunktiot

use NoPayn\Signature;

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

Virheenkäsittely

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
}

Tilausten tilat

Tila	Lopullinen?	Kuvaus
`new`	Ei	Tilaus luotu
`processing`	Ei	Maksu käynnissä
`completed`	Kyllä	Maksu onnistui — toimita tavarat
`cancelled`	Kyllä	Asiakas peruutti maksun
`expired`	Kyllä	Maksulinkki vanheni
`error`	Kyllä	Tekninen virhe

Webhook-parhaat käytännöt

Vahvista aina API:n kautta — webhook-data sisältää vain tilauksen tunnisteen, ei koskaan tilaa. SDK:n verifyWebhook() tekee tämän automaattisesti.
Palauta HTTP 200 kuittauksena. Mikä tahansa muu koodi käynnistää enintään 10 uudelleenyritystä (2 minuutin välein).
Toteuta varapolleri — yli 10 minuuttia vanhoille tilauksille, jotka eivät ole saavuttaneet lopullista tilaa, pollaa getOrder() turvavarana.
Ole idempotentti — saatat vastaanottaa saman webhookin useita kertoja.

Testikortit

Käytä näitä kortteja Cost+:n testitilassa (sandbox-verkkosivusto):

Kortti	Numero	Huomautukset
Visa (onnistunut)	`4111 1111 1111 1111`	Mikä tahansa CVV
Mastercard (onnistunut)	`5544 3300 0003 7`	Mikä tahansa CVV
Visa (hylätty)	`4111 1111 1111 1105`	Do Not Honor
Visa (riittämätön kate)	`4111 1111 1111 1151`	Insufficient Funds

Käytä mitä tahansa tulevaa voimassaolopäivää ja mitä tahansa 3-numeroista CVC:tä.

Demosovellus

Docker-pohjainen demosovellus sisältyy GitHub-tietovarastoon täyden maksukulun testaamiseksi.

Tuki

Tarvitsetko apua? Ota yhteyttä tukitiimiimme osoitteessa support@costplus.io.

On this page