PHP
Официално PHP SDK за разплащателния шлюз Cost+
Официално PHP SDK за разплащателния шлюз Cost+. Опростява потока за пренасочване към HPP (хоствана страница за плащане), HMAC подписването на данни и верификацията на уебхукове.
Характеристики
- Нулеви външни зависимости — използва само вградени PHP разширения (
curl,json,hash) - PHP 8.1+ с readonly свойства, именувани аргументи и строги типове
- HMAC-SHA256 генериране на подписи и верификация с постоянно време чрез
hash_equals - Автоматично съответствие snake_case/camelCase между API и SDK
- Анализиране на уебхукове + верификация на поръчки, базирана на API
- Тествано с PHP 8.1, 8.2 и 8.3
Изисквания
- PHP 8.1 или по-нова версия
- Разширения:
curl,json(и двете са включени в стандартния PHP) - Търговски акаунт в Cost+ — dashboard.costplus.io
Инсталация
composer require nopayn/sdkБързо начало
1. Инициализиране на клиента
use NoPayn\NoPaynClient;
$nopayn = new NoPaynClient([
'apiKey' => 'your-api-key',
'merchantId' => 'your-project',
]);2. Създаване на плащане и пренасочване към 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. Обработка на уебхука
$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 справочник
new NoPaynClient(array $config)
| Параметър | Тип | Задължителен | По подразбиране |
|---|---|---|---|
apiKey | string | Да | — |
merchantId | string | Да | — |
baseUrl | string | Не | https://api.nopayn.co.uk |
$client->createOrder(array $params): array
Създава поръчка чрез POST /v1/orders/.
| Параметър | Тип | Задължителен | Описание |
|---|---|---|---|
amount | int | да | Сума в ISO 4217 второстепенна единица на валутата (например центове за EUR) |
currency | string | Да | ISO 4217 код (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | string | Не | Ваш вътрешен идентификатор на поръчка |
description | string | Не | Описание на поръчката |
returnUrl | string | Не | Пренасочване след успешно плащане |
failureUrl | string | Не | Пренасочване при отказ/изтичане/грешка |
webhookUrl | string | Не | Асинхронни известия за промяна на статуса |
locale | string | Не | Език на HPP (en-GB, de-DE, nl-NL и др.) |
paymentMethods | string[] | Не | Филтриране на HPP методи |
expirationPeriod | string | Не | ISO 8601 продължителност (PT30M) |
Налични методи на плащане: credit-card, apple-pay, google-pay, vipps-mobilepay
$client->getOrder(string $orderId): array
Извлича детайли на поръчка чрез GET /v1/orders/{id}/.
$client->createRefund(string $orderId, int $amount, ?string $description = null): array
Издава пълно или частично възстановяване чрез POST /v1/orders/{id}/refunds/.
$client->generatePaymentUrl(array $params): array
Удобен метод, който създава поръчка и връща:
[
'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
Генерира HMAC-SHA256 шестнадесетичен подпис.
$client->verifySignature(int $amount, string $currency, string $orderId, string $signature): bool
Верификация с постоянно време на HMAC-SHA256 подпис.
$client->verifyWebhook(string $rawBody): array
Анализира тялото на уебхука, след което извиква GET /v1/orders/{id}/, за да провери действителния статус.
Самостоятелни HMAC помощни функции
use NoPayn\Signature;
$sig = Signature::generate('your-api-key', 1295, 'EUR', 'order-uuid');
$ok = Signature::verify('your-api-key', 1295, 'EUR', 'order-uuid', $sig);Обработка на грешки
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
}Статуси на поръчки
| Статус | Финален? | Описание |
|---|---|---|
new | Не | Поръчката е създадена |
processing | Не | Плащането е в ход |
completed | Да | Плащането е успешно — доставете стоката |
cancelled | Да | Плащането е отменено от клиента |
expired | Да | Линкът за плащане е изтекъл |
error | Да | Техническа грешка |
Добри практики за уебхукове
- Винаги проверявайте чрез API — данните от уебхука съдържат само идентификатора на поръчката, никога статуса.
verifyWebhook()на SDK-то прави това автоматично. - Връщайте HTTP 200, за да потвърдите получаването. Всеки друг код задейства до 10 повторни опита (през 2 минути).
- Въведете резервен polling — за поръчки, по-стари от 10 минути, които не са достигнали финален статус, правете polling с
getOrder()като мрежа за безопасност. - Бъдете идемпотентни — може да получите един и същ уебхук многократно.
Тестови карти
Използвайте тези карти в тестов режим на Cost+ (sandbox уебсайт):
| Карта | Номер | Бележки |
|---|---|---|
| Visa (успех) | 4111 1111 1111 1111 | Произволен CVV |
| Mastercard (успех) | 5544 3300 0003 7 | Произволен CVV |
| Visa (отхвърлена) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (недостатъчни средства) | 4111 1111 1111 1151 | Insufficient Funds |
Използвайте произволна бъдеща дата на валидност и произволен 3-цифрен CVC.
Демо приложение
Демо приложение, базирано на Docker, е включено в GitHub хранилището за тестване на пълния поток на плащане.
Поддръжка
Нуждаете се от помощ? Свържете се с нашия екип за поддръжка на support@costplus.io.