PHP
SDK oifigiúil PHP do gheata íocaíochta Cost+
SDK oifigiúil PHP do gheata íocaíochta Cost+. Simpliú an tsreabha atreoraithe HPP (Leathanach Íocaíochta Óstáilte), síniú sonraí HMAC, agus fíorú webhook.
Gnéithe
- Nialas spleáchais sheachtracha -- ní úsáideann sé ach eisínteachtaí ionsuite PHP (
curl,json,hash) - PHP 8.1+ le hairíonna inléite-amháin, argóintí ainmnithe, agus cineálacha dochta
- Giniúint sínithe HMAC-SHA256 agus fíorú ama-leanúnaigh tríd an
hash_equals - Mapáil uathoibríoch snake_case/camelCase idir an API agus an SDK
- Parsáil webhook + fíorú ordaithe bunaithe ar API
- Tástáilte ar fud PHP 8.1, 8.2, agus 8.3
Riachtanais
- PHP 8.1 nó níos déanaí
- Eisínteachtaí:
curl,json(an dá cheann san áireamh i PHP caighdeánach) - Cuntas ceannaithe Cost+ -- dashboard.costplus.io
Suiteáil
composer require nopayn/sdkMearthosnú
1. Túsaigh an Cliant
use NoPayn\NoPaynClient;
$nopayn = new NoPaynClient([
'apiKey' => 'your-api-key',
'merchantId' => 'your-project',
]);2. Cruthaigh Íocaíocht agus Atreorófar chuig an 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. Láimhseáil an 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);Tagairt API
new NoPaynClient(array $config)
| Paraiméadar | Cineál | Riachtanach | Réamhshocrú |
|---|---|---|---|
apiKey | string | Tá | -- |
merchantId | string | Tá | -- |
baseUrl | string | Níl | https://api.nopayn.co.uk |
$client->createOrder(array $params): array
Cruthaíonn ordú tríd an POST /v1/orders/.
| Paraiméadar | Cineál | Riachtanach | Cur Síos |
|---|---|---|---|
amount | int | Tá | Méid i mionaonad ISO 4217 an airgeadra (mar shampla, cent le haghaidh EUR) |
currency | string | Tá | Cód ISO 4217 (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | string | Níl | Do thagairt inmheánach ordaithe |
description | string | Níl | Cur síos ar an ordú |
returnUrl | string | Níl | Atreorú tar éis íocaíochta rathúla |
failureUrl | string | Níl | Atreorú ar cheallú/éag/earráid |
webhookUrl | string | Níl | Fógraí athraithe stádais asincrónach |
locale | string | Níl | Teanga HPP (en-GB, de-DE, nl-NL, srl.) |
paymentMethods | string[] | Níl | Scag modhanna HPP |
expirationPeriod | string | Níl | Fad ISO 8601 (PT30M) |
Modhanna íocaíochta ar fáil: credit-card, apple-pay, google-pay, vipps-mobilepay
$client->getOrder(string $orderId): array
Faigheann sonraí ordaithe tríd an GET /v1/orders/{id}/.
$client->createRefund(string $orderId, int $amount, ?string $description = null): array
Eisíonn aisíocaíocht iomlán nó pháirteach tríd an POST /v1/orders/{id}/refunds/.
$client->generatePaymentUrl(array $params): array
Modh áise a chruthaíonn ordú agus a sheolann ar ais:
[
'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
Gineann síniú HMAC-SHA256 hex.
$client->verifySignature(int $amount, string $currency, string $orderId, string $signature): bool
Fíorú ama-leanúnaigh ar shíniú HMAC-SHA256.
$client->verifyWebhook(string $rawBody): array
Parsáileann corp an webhook, ansin glaonn GET /v1/orders/{id}/ chun an stádas iarbhír a fhíorú.
Fóntais HMAC Neamhspleácha
use NoPayn\Signature;
$sig = Signature::generate('your-api-key', 1295, 'EUR', 'order-uuid');
$ok = Signature::verify('your-api-key', 1295, 'EUR', 'order-uuid', $sig);Láimhseáil Earráidí
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
}Stádais Ordaithe
| Stádas | Deiridh? | Cur Síos |
|---|---|---|
new | Níl | Ordú cruthaithe |
processing | Níl | Íocaíocht ar siúl |
completed | Tá | D'éirigh leis an íocaíocht -- seachaid na hearraí |
cancelled | Tá | Cheal an custaiméir an íocaíocht |
expired | Tá | D'éag an nasc íocaíochta |
error | Tá | Teip theicniúil |
Dea-Chleachtais Webhook
- Fíoraigh tríd an API i gcónaí -- ní bhíonn ach aitheantas an ordaithe sa sonraí webhook, ní an stádas riamh. Déanann
verifyWebhook()an SDK é seo go huathoibríoch. - Seol HTTP 200 ar ais chun fáiltiú a admháil. Spreagann aon chód eile suas le 10 n-atriail (2 nóiméad eatarthu).
- Cuir cúltaca pólaí i bhfeidhm -- d'orduithe atá níos sine ná 10 nóiméad nach bhfuil stádas deiridh bainte amach acu, pólail
getOrder()mar líontán sábháilteachta. - Bí idéimpotent -- d'fhéadfá an webhook céanna a fháil arís is arís eile.
Cártaí Tástála
Úsáid na cártaí seo i mód tástála Cost+ (suíomh gréasáin gaineamhchláir):
| Cárta | Uimhir | Nótaí |
|---|---|---|
| Visa (rath) | 4111 1111 1111 1111 | Aon CVV |
| Mastercard (rath) | 5544 3300 0003 7 | Aon CVV |
| Visa (diúltaithe) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (cistí neamhleor) | 4111 1111 1111 1151 | Insufficient Funds |
Úsáid aon dáta éaga amach anseo agus aon CVC 3 dhigit.
Aip Thaispeána
Tá aip thaispeána Docker-bhunaithe san áireamh sa stór GitHub chun an sreabhadh íocaíochta iomlán a thástáil.
Tacaíocht
Cabhair ag teastáil? Déan teagmháil lenár bhfoireann tacaíochta ag support@costplus.io.