Node.js / TypeScript
Uradni Node.js SDK za plačilni prehod Cost+
Uradni Node.js/TypeScript SDK za plačilni prehod Cost+. Poenostavlja tok preusmeritve HPP (gostovane plačilne strani), HMAC podpisovanje koristnih podatkov in preverjanje webhook-ov.
Lastnosti
- Brez odvisnosti — uporablja le vgrajeni Node.js
cryptoinfetch - Polni TypeScript tipi z mapami deklaracij
- HMAC-SHA256 generiranje podpisov in preverjanje s konstantnim časom
- Samodejno preslikavanje snake_case/camelCase med API-jem in SDK-jem
- Razčlenjevanje webhook-ov + preverjanje naročil na osnovi API-ja
- Testirano na Node.js 18, 20 in 22
Zahteve
- Node.js 18 ali novejši (uporablja vgrajeni
fetch) - Trgovski račun Cost+ — dashboard.costplus.io
Namestitev
npm install nopayn-node-sdkHitri začetek
1. Inicializirajte odjemalca
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. Ustvarite plačilo in preusmerite 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',
});
// Preusmerite stranko
// result.orderUrl → HPP (stranka izbere plačilno metodo)
// result.paymentUrl → neposredna povezava do plačilne metode prve transakcije
// result.signature → HMAC-SHA256 za preverjanje
// result.orderId → NoPayn UUID naročila3. Obdelajte 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') {
// Izpolnite naročilo
}
res.sendStatus(200);
});API referenca
new NoPaynClient(config)
| Parameter | Tip | Obvezno | Privzeto |
|---|---|---|---|
apiKey | string | Da | — |
merchantId | string | Da | — |
baseUrl | string | Ne | https://api.nopayn.co.uk |
client.createOrder(params)
Ustvari naročilo prek POST /v1/orders/.
| Parameter | Tip | Obvezno | Opis |
|---|---|---|---|
amount | number | ja | Znesek v manjši enoti ISO 4217 valute (na primer centi za EUR) |
currency | string | Da | Koda ISO 4217 (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | string | Ne | Vaša interna referenca naročila |
description | string | Ne | Opis naročila |
returnUrl | string | Ne | Preusmeritev po uspešnem plačilu |
failureUrl | string | Ne | Preusmeritev ob preklicu/poteku/napaki |
webhookUrl | string | Ne | Asinhrona obvestila o spremembi statusa |
locale | string | Ne | Jezik HPP (en-GB, de-DE, nl-NL itd.) |
paymentMethods | PaymentMethod[] | Ne | Filtriraj metode HPP |
expirationPeriod | string | Ne | Trajanje ISO 8601 (PT30M) |
Razpoložljive plačilne metode: credit-card, apple-pay, google-pay, vipps-mobilepay
client.getOrder(orderId)
Pridobi podrobnosti naročila prek GET /v1/orders/{id}/.
client.createRefund(orderId, amount, description?)
Izda celotno ali delno vračilo prek POST /v1/orders/{id}/refunds/.
client.generatePaymentUrl(params)
Priročna metoda, ki ustvari naročilo in vrne:
{
orderId: string; // NoPayn UUID naročila
orderUrl: string; // HPP URL
paymentUrl?: string; // Neposredni plačilni URL (prva transakcija)
signature: string; // HMAC-SHA256 od amount:currency:orderId
order: Order; // Celoten objekt naročila
}client.generateSignature(amount, currency, orderId)
Generira HMAC-SHA256 šestnajstiški podpis. Kanonično sporočilo je ${amount}:${currency}:${orderId}, podpisano z API ključem.
client.verifySignature(amount, currency, orderId, signature)
Preverjanje HMAC-SHA256 podpisa s konstantnim časom. Vrne true, če je veljaven.
client.verifyWebhook(rawBody)
Razčleni telo webhook-a, nato pokliče GET /v1/orders/{id}/ za preverjanje dejanskega statusa. Vrne:
{
orderId: string;
order: Order; // Preverjeno prek API-ja
isFinal: boolean; // true za completed/cancelled/expired/error
}client.parseWebhookBody(rawBody)
Razčleni in validira telo webhook-a brez klicanja API-ja.
Samostojne HMAC pripomočke
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);Obravnava napak
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 naročil
| Status | Končni? | Opis |
|---|---|---|
new | Ne | Naročilo ustvarjeno |
processing | Ne | Plačilo v teku |
completed | Da | Plačilo uspešno — dostavite blago |
cancelled | Da | Plačilo preklicano s strani stranke |
expired | Da | Plačilna povezava je potekla |
error | Da | Tehnična napaka |
Najboljše prakse za webhook-e
- Vedno preverite prek API-ja — koristni podatki webhook-a vsebujejo samo ID naročila, nikoli statusa. SDK-jev
verifyWebhook()to naredi samodejno. - Vrnite HTTP 200 za potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
- Implementirajte rezervno poizvedovanje — za naročila, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte
getOrder()kot varnostno mrežo. - Bodite idempotentni — isti webhook lahko prejmete večkrat.
Testne kartice
Uporabite te kartice v testnem načinu Cost+ (spletno mesto peskovnika):
| Kartica | Številka | Opombe |
|---|---|---|
| Visa (uspeh) | 4111 1111 1111 1111 | Katerikoli CVV |
| Mastercard (uspeh) | 5544 3300 0003 7 | Katerikoli CVV |
| Visa (zavrnjena) | 4111 1111 1111 1105 | Zavrnitev |
| Visa (nezadostna sredstva) | 4111 1111 1111 1151 | Nezadostna sredstva |
Uporabite katerikoli prihodnji datum veljavnosti in katerokoli 3-mestno CVC kodo.
Predstavitvena aplikacija
Predstavitvena aplikacija na osnovi Docker je vključena v GitHub repozitorij za testiranje celotnega plačilnega toka:
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 --buildOdprite http://localhost:3000 za ogled predstavitvene strani za zaključek nakupa.
Podpora
Potrebujete pomoč? Obrnite se na našo ekipo za podporo na support@costplus.io.