Node.js / TypeScript
Službeni Node.js SDK za Cost+ platni pristupnik
Službeni Node.js/TypeScript SDK za Cost+ platni pristupnik. Pojednostavljuje tijek preusmjeravanja na HPP (hosted stranicu za plaćanje), HMAC potpisivanje podataka i verifikaciju webhookova.
Značajke
- Bez ovisnosti — koristi samo ugrađene Node.js
cryptoifetch - Potpuni TypeScript tipovi s mapama deklaracija
- HMAC-SHA256 generiranje potpisa i verifikacija konstantnim vremenom
- Automatsko mapiranje snake_case/camelCase između API-ja i SDK-a
- Raščlamba webhookova + verifikacija narudžbe temeljena na API-ju
- Testirano na Node.js 18, 20 i 22
Zahtjevi
- Node.js 18 ili noviji (koristi ugrađeni
fetch) - Cost+ trgovački račun — dashboard.costplus.io
Instalacija
npm install nopayn-node-sdkBrzi početak
1. Inicijalizirajte klijent
import { NoPaynClient } from 'nopayn-node-sdk';
const nopayn = new NoPaynClient({
apiKey: 'your-api-key', // From the NoPayn merchant portal
merchantId: 'your-project', // Your project/merchant ID
});2. Stvorite plaćanje i preusmjerite na HPP
const result = await 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 UUID3. Obradite webhook
app.post('/webhook', async (req, res) => {
const verified = await nopayn.verifyWebhook(JSON.stringify(req.body));
console.log(verified.order.status); // 'completed', 'cancelled', etc.
console.log(verified.isFinal); // true when the order won't change
if (verified.order.status === 'completed') {
// Fulfil the order
}
res.sendStatus(200);
});API referenca
new NoPaynClient(config)
| Parametar | Tip | Obavezno | Zadano |
|---|---|---|---|
apiKey | string | Da | — |
merchantId | string | Da | — |
baseUrl | string | Ne | https://api.nopayn.co.uk |
client.createOrder(params)
Stvara narudžbu putem POST /v1/orders/.
| Parametar | Tip | Obavezno | Opis |
|---|---|---|---|
amount | number | Da | Iznos u manjoj jedinici ISO 4217 valute (na primjer, centi za EUR) |
currency | string | Da | ISO 4217 kod (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | string | Ne | Vaša interna referenca narudžbe |
description | string | Ne | Opis narudžbe |
returnUrl | string | Ne | Preusmjeravanje nakon uspješnog plaćanja |
failureUrl | string | Ne | Preusmjeravanje pri poništenju/isteku/grešci |
webhookUrl | string | Ne | Asinkrone obavijesti o promjeni statusa |
locale | string | Ne | Jezik HPP-a (en-GB, de-DE, nl-NL itd.) |
paymentMethods | PaymentMethod[] | Ne | Filtriranje HPP načina |
expirationPeriod | string | Ne | ISO 8601 trajanje (PT30M) |
Dostupni načini plaćanja: credit-card, apple-pay, google-pay, vipps-mobilepay
client.getOrder(orderId)
Dohvaća detalje narudžbe putem GET /v1/orders/{id}/.
client.createRefund(orderId, amount, description?)
Izdaje potpuni ili djelomični povrat putem POST /v1/orders/{id}/refunds/.
client.generatePaymentUrl(params)
Praktična metoda koja stvara narudžbu i vraća:
{
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: Order; // Full order object
}client.generateSignature(amount, currency, orderId)
Generira HMAC-SHA256 heksadecimalni potpis. Kanonska poruka je ${amount}:${currency}:${orderId}, potpisana API ključem.
client.verifySignature(amount, currency, orderId, signature)
Verifikacija HMAC-SHA256 potpisa konstantnim vremenom. Vraća true ako je valjan.
client.verifyWebhook(rawBody)
Raščlanjuje tijelo webhooka, zatim poziva GET /v1/orders/{id}/ za provjeru stvarnog statusa. Vraća:
{
orderId: string;
order: Order; // Verified via API
isFinal: boolean; // true for completed/cancelled/expired/error
}client.parseWebhookBody(rawBody)
Raščlanjuje i validira tijelo webhooka bez pozivanja API-ja.
Samostalni HMAC alati
import { generateSignature, verifySignature } from 'nopayn-node-sdk';
const sig = generateSignature('your-api-key', 1295, 'EUR', 'order-uuid');
const ok = verifySignature('your-api-key', 1295, 'EUR', 'order-uuid', sig);Rukovanje greškama
import { NoPaynApiError, NoPaynError, NoPaynWebhookError } from 'nopayn-node-sdk';
try {
await nopayn.createOrder({ amount: 100, currency: 'EUR' });
} catch (err) {
if (err instanceof NoPaynApiError) {
console.error(err.statusCode); // 401, 400, etc.
console.error(err.errorBody); // Raw API error response
} else if (err instanceof NoPaynError) {
console.error(err.message); // Network or parsing error
}
}Statusi narudžbe
| Status | Konačan? | Opis |
|---|---|---|
new | Ne | Narudžba stvorena |
processing | Ne | Plaćanje u tijeku |
completed | Da | Plaćanje uspjelo — isporučite robu |
cancelled | Da | Plaćanje poništeno od strane kupca |
expired | Da | Poveznica za plaćanje je istekla |
error | Da | Tehnički kvar |
Najbolje prakse za webhookove
- Uvijek provjerite putem API-ja — webhook podaci sadrže samo ID narudžbe, nikada status. SDK-ov
verifyWebhook()to radi automatski. - Vratite HTTP 200 za potvrdu primitka. Bilo koji drugi kod pokreće do 10 ponovnih pokušaja (svake 2 minute).
- Implementirajte rezervno anketiranje — za narudžbe starije od 10 minuta koje nisu dosegle konačni status, anketirajte
getOrder()kao sigurnosnu mrežu. - Budite idempotentni — možete primiti isti webhook više puta.
Testne kartice
Koristite ove kartice u Cost+ testnom načinu (sandbox web stranica):
| Kartica | Broj | Napomene |
|---|---|---|
| Visa (uspjeh) | 4111 1111 1111 1111 | Bilo koji CVV |
| Mastercard (uspjeh) | 5544 3300 0003 7 | Bilo koji CVV |
| Visa (odbijena) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedovoljna sredstva) | 4111 1111 1111 1151 | Insufficient Funds |
Koristite bilo koji budući datum isteka i bilo koji 3-znamenkasti CVC.
Demo aplikacija
Docker-bazirana demo aplikacija uključena je u GitHub repozitoriju za testiranje potpunog tijeka plaćanja:
cd demo
cat > .env << EOF
NOPAYN_API_KEY=your-api-key
NOPAYN_MERCHANT_ID=your-merchant-id
PUBLIC_URL=http://localhost:3000
EOF
docker compose up --buildOtvorite http://localhost:3000 za prikaz demo stranice blagajne.
Podrška
Trebate pomoć? Obratite se našem timu za podršku na support@costplus.io.