Cost+Docs

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)

ПараметърТипЗадължителенПо подразбиране
apiKeystringДа—
merchantIdstringДа—
baseUrlstringНеhttps://api.nopayn.co.uk

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

Създава поръчка чрез POST /v1/orders/.

ПараметърТипЗадължителенОписание
amountintдаСума в ISO 4217 второстепенна единица на валутата (например центове за EUR)
currencystringДаISO 4217 код (EUR, GBP, USD, NOK, SEK)
merchantOrderIdstringНеВаш вътрешен идентификатор на поръчка
descriptionstringНеОписание на поръчката
returnUrlstringНеПренасочване след успешно плащане
failureUrlstringНеПренасочване при отказ/изтичане/грешка
webhookUrlstringНеАсинхронни известия за промяна на статуса
localestringНеЕзик на HPP (en-GB, de-DE, nl-NL и др.)
paymentMethodsstring[]НеФилтриране на HPP методи
expirationPeriodstringНе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ДаТехническа грешка

Добри практики за уебхукове

  1. Винаги проверявайте чрез API — данните от уебхука съдържат само идентификатора на поръчката, никога статуса. verifyWebhook() на SDK-то прави това автоматично.
  2. Връщайте HTTP 200, за да потвърдите получаването. Всеки друг код задейства до 10 повторни опита (през 2 минути).
  3. Въведете резервен polling — за поръчки, по-стари от 10 минути, които не са достигнали финален статус, правете polling с getOrder() като мрежа за безопасност.
  4. Бъдете идемпотентни — може да получите един и същ уебхук многократно.

Тестови карти

Използвайте тези карти в тестов режим на Cost+ (sandbox уебсайт):

КартаНомерБележки
Visa (успех)4111 1111 1111 1111Произволен CVV
Mastercard (успех)5544 3300 0003 7Произволен CVV
Visa (отхвърлена)4111 1111 1111 1105Do Not Honor
Visa (недостатъчни средства)4111 1111 1111 1151Insufficient Funds

Използвайте произволна бъдеща дата на валидност и произволен 3-цифрен CVC.

Демо приложение

Демо приложение, базирано на Docker, е включено в GitHub хранилището за тестване на пълния поток на плащане.

Поддръжка

Нуждаете се от помощ? Свържете се с нашия екип за поддръжка на support@costplus.io.

On this page