PHP

Officiele PHP SDK voor de Cost+ betaalgateway. Vereenvoudigt de HPP (Hosted Payment Page) doorverwijzingsflow, HMAC-payloadondertekening en webhookverificatie.

Kenmerken

Geen externe afhankelijkheden — gebruikt alleen ingebouwde PHP-extensies (curl, json, hash)
PHP 8.1+ met readonly properties, named arguments en strict types
HMAC-SHA256-handtekeninggeneratie en constant-time verificatie via hash_equals
Automatische snake_case/camelCase-mapping tussen de API en de SDK
Webhook-parsing + API-gebaseerde bestellingsverificatie
Getest op PHP 8.1, 8.2 en 8.3

Vereisten

PHP 8.1 of hoger
Extensies: curl, json (beide inbegrepen in standaard PHP)
Een Cost+ handelaarsaccount — dashboard.costplus.io

Installatie

composer require nopayn/sdk

Snelstart

1. De client initialiseren

use NoPayn\NoPaynClient;

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

2. Een betaling aanmaken en doorverwijzen naar de 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. De webhook afhandelen

$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-referentie

`new NoPaynClient(array $config)`

Parameter	Type	Vereist	Standaard
`apiKey`	`string`	Ja	—
`merchantId`	`string`	Ja	—
`baseUrl`	`string`	Nee	`https://api.nopayn.co.uk`

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

Maakt een bestelling aan via POST /v1/orders/.

Parameter	Type	Vereist	Beschrijving
`amount`	`int`	Ja	Bedrag in kleinste valuta-eenheid (centen)
`currency`	`string`	Ja	ISO 4217-code (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nee	Uw interne bestellingsreferentie
`description`	`string`	Nee	Bestellingsbeschrijving
`returnUrl`	`string`	Nee	Doorverwijzing na geslaagde betaling
`failureUrl`	`string`	Nee	Doorverwijzing bij annulering/verloop/fout
`webhookUrl`	`string`	Nee	Asynchrone statuswijzigingsmeldingen
`locale`	`string`	Nee	HPP-taal (`en-GB`, `de-DE`, `nl-NL`, enz.)
`paymentMethods`	`string[]`	Nee	HPP-methoden filteren
`expirationPeriod`	`string`	Nee	ISO 8601-duur (`PT30M`)

Beschikbare betaalmethoden: credit-card, apple-pay, google-pay, vipps-mobilepay

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

Haalt bestellingsdetails op via GET /v1/orders/{id}/.

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

Voert een volledige of gedeeltelijke terugbetaling uit via POST /v1/orders/{id}/refunds/.

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

Hulpmethode die een bestelling aanmaakt en retourneert:

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

Genereert een HMAC-SHA256 hex-handtekening.

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

Constant-time verificatie van een HMAC-SHA256-handtekening.

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

Parst de webhook-body en roept vervolgens GET /v1/orders/{id}/ aan om de werkelijke status te verifieren.

Standalone HMAC-hulpmiddelen

use NoPayn\Signature;

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

Foutafhandeling

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
}

Bestellingsstatussen

Status	Definitief?	Beschrijving
`new`	Nee	Bestelling aangemaakt
`processing`	Nee	Betaling wordt verwerkt
`completed`	Ja	Betaling geslaagd — lever de goederen
`cancelled`	Ja	Betaling geannuleerd door klant
`expired`	Ja	Betaallink verlopen
`error`	Ja	Technische storing

Best practices voor webhooks

Verifieer altijd via de API — de webhook-payload bevat alleen het bestelling-ID, nooit de status. De verifyWebhook() van de SDK doet dit automatisch.
Retourneer HTTP 200 om de ontvangst te bevestigen. Elke andere code triggert tot 10 herhaalpogingen (2 minuten tussenpozen).
Implementeer een backup-poller — voor bestellingen ouder dan 10 minuten die nog geen definitieve status hebben bereikt, poll getOrder() als vangnet.
Wees idempotent — u kunt dezelfde webhook meerdere keren ontvangen.

Testkaarten

Gebruik deze kaarten in Cost+ testmodus (sandbox-website):

Kaart	Nummer	Opmerkingen
Visa (geslaagd)	`4111 1111 1111 1111`	Willekeurige CVV
Mastercard (geslaagd)	`5544 3300 0003 7`	Willekeurige CVV
Visa (geweigerd)	`4111 1111 1111 1105`	Do Not Honor
Visa (onvoldoende saldo)	`4111 1111 1111 1151`	Insufficient Funds

Gebruik een willekeurige toekomstige vervaldatum en een willekeurige 3-cijferige CVC.

Demo-app

Een op Docker gebaseerde demo-app is opgenomen in de GitHub-repository om de volledige betalingsflow te testen.

Ondersteuning

Hulp nodig? Neem contact op met ons supportteam via support@costplus.io.

On this page