Node.js / TypeScript
SDK uffiċjali ta' Node.js għall-gateway tal-ħlas Cost+
SDK uffiċjali ta' Node.js/TypeScript għall-gateway tal-ħlas Cost+. Jissimplifika l-flusso ta' redirect tal-HPP (Paġna ta' Ħlas Ospitata), il-firma tal-payload HMAC, u l-verifika tal-webhooks.
Karatteristiċi
- Żero dipendenzi — juża biss
cryptoufetchintegrati f'Node.js - Tipi sħaħ ta' TypeScript b'mapep tad-dikjarazzjonijiet
- Ġenerazzjoni ta' firma HMAC-SHA256 u verifika b'ħin kostanti
- Mappa awtomatika ta' snake_case/camelCase bejn l-API u l-SDK
- Ipparsjar tal-webhooks + verifika tal-ordni bbażata fuq l-API
- Ittestjat fuq Node.js 18, 20, u 22
Rekwiżiti
- Node.js 18 jew aktar tard (juża
fetchintegrat) - Kont ta' kummerċjant Cost+ — dashboard.costplus.io
Installazzjoni
npm install nopayn-node-sdkBidu Malajr
1. Inizjalizza l-Klijent
import { NoPaynClient } from 'nopayn-node-sdk';
const nopayn = new NoPaynClient({
apiKey: 'your-api-key', // Mill-portal tal-kummerċjant NoPayn
merchantId: 'your-project', // L-ID tal-proġett/kummerċjant tiegħek
});2. Oħloq Ħlas u Irridirezzjona lejn il-HPP
const result = await nopayn.generatePaymentUrl({
amount: 1295, // €12.95 f'ċenteżmi
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',
});
// Irridirezzjona l-klijent
// result.orderUrl → HPP (il-klijent jagħżel il-metodu ta' ħlas)
// result.paymentUrl → link dirett lejn il-metodu ta' ħlas tal-ewwel tranżazzjoni
// result.signature → HMAC-SHA256 għall-verifika
// result.orderId → UUID tal-ordni NoPayn3. Ittratta l-Webhook
app.post('/webhook', async (req, res) => {
const verified = await nopayn.verifyWebhook(JSON.stringify(req.body));
console.log(verified.order.status); // 'completed', 'cancelled', eċċ.
console.log(verified.isFinal); // true meta l-ordni ma tinbidilx aktar
if (verified.order.status === 'completed') {
// Issodisfa l-ordni
}
res.sendStatus(200);
});Referenza tal-API
new NoPaynClient(config)
| Parametru | Tip | Meħtieġ | Default |
|---|---|---|---|
apiKey | string | Iva | — |
merchantId | string | Iva | — |
baseUrl | string | Le | https://api.nopayn.co.uk |
client.createOrder(params)
Joħloq ordni permezz ta' POST /v1/orders/.
| Parametru | Tip | Meħtieġ | Deskrizzjoni |
|---|---|---|---|
amount | number | Iva | Ammont fl-unità minuri ISO 4217 tal-munita (per eżempju, ċenteżmi għal EUR) |
currency | string | Iva | Kodiċi ISO 4217 (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | string | Le | Ir-referenza interna tal-ordni tiegħek |
description | string | Le | Deskrizzjoni tal-ordni |
returnUrl | string | Le | Redirect wara ħlas li rnexxielu |
failureUrl | string | Le | Redirect fuq kanċellazzjoni/skadenza/żball |
webhookUrl | string | Le | Notifiki asinkroni ta' bidla fl-istatus |
locale | string | Le | Lingwa tal-HPP (en-GB, de-DE, nl-NL, eċċ.) |
paymentMethods | PaymentMethod[] | Le | Iffiltra l-metodi tal-HPP |
expirationPeriod | string | Le | Tul ta' żmien ISO 8601 (PT30M) |
Metodi ta' ħlas disponibbli: credit-card, apple-pay, google-pay, vipps-mobilepay
client.getOrder(orderId)
Jiġbed id-dettalji tal-ordni permezz ta' GET /v1/orders/{id}/.
client.createRefund(orderId, amount, description?)
Joħroġ rifużjoni sħiħa jew parzjali permezz ta' POST /v1/orders/{id}/refunds/.
client.generatePaymentUrl(params)
Metodu ta' konvenjenza li joħloq ordni u jirritorna:
{
orderId: string; // UUID tal-ordni NoPayn
orderUrl: string; // URL tal-HPP
paymentUrl?: string; // URL ta' ħlas dirett (l-ewwel tranżazzjoni)
signature: string; // HMAC-SHA256 ta' amount:currency:orderId
order: Order; // Oġġett sħiħ tal-ordni
}client.generateSignature(amount, currency, orderId)
Jiġġenera firma HMAC-SHA256 hex. Il-messaġġ kanoniku huwa ${amount}:${currency}:${orderId}, iffirmat biċ-ċavetta API.
client.verifySignature(amount, currency, orderId, signature)
Verifika b'ħin kostanti ta' firma HMAC-SHA256. Tirritorna true jekk valida.
client.verifyWebhook(rawBody)
Jipparsja l-korp tal-webhook, imbagħad isejjaħ GET /v1/orders/{id}/ biex jivverifika l-istatus attwali. Jirritorna:
{
orderId: string;
order: Order; // Ivverifikata permezz tal-API
isFinal: boolean; // true għal completed/cancelled/expired/error
}client.parseWebhookBody(rawBody)
Jipparsja u jivvalida korp tal-webhook mingħajr ma jsejjaħ l-API.
Utilitajiet HMAC Standalone
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);Trattar tal-Żbalji
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, eċċ.
console.error(err.errorBody); // Risposta ta' żball mhux ipproċessata tal-API
} else if (err instanceof NoPaynError) {
console.error(err.message); // Żball tan-network jew tal-ipparsjar
}
}Statuses tal-Ordni
| Status | Finali? | Deskrizzjoni |
|---|---|---|
new | Le | Ordni maħluqa |
processing | Le | Ħlas qed isir |
completed | Iva | Ħlas irnexxielu — ikkonsenja l-prodotti |
cancelled | Iva | Ħlas ikkanċellat mill-klijent |
expired | Iva | Link tal-ħlas skada |
error | Iva | Falliment tekniku |
L-Aħjar Prattiċi għall-Webhooks
- Dejjem ivverifika permezz tal-API — il-payload tal-webhook fih biss l-ID tal-ordni, qatt l-istatus. Il-
verifyWebhook()tal-SDK jagħmel dan awtomatikament. - Irritorna HTTP 200 biex tikkonferma r-riċevuta. Kwalunkwe kodiċi ieħor jiskatta sa 10 retries (2 minuti bejn xulxin).
- Implimenta backup poller — għal ordnijiet itqal minn 10 minuti li għadhom ma laħqux status finali, agħmel polling ta'
getOrder()bħala xibka ta' sigurtà. - Kun idempotenti — tista' tirċievi l-istess webhook aktar minn darba.
Karti tat-Test
Uża dawn il-karti f'modalità tat-test ta' Cost+ (website sandbox):
| Karta | Numru | Noti |
|---|---|---|
| Visa (suċċess) | 4111 1111 1111 1111 | Kwalunkwe CVV |
| Mastercard (suċċess) | 5544 3300 0003 7 | Kwalunkwe CVV |
| Visa (miċħuda) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (fondi insuffiċjenti) | 4111 1111 1111 1151 | Insufficient Funds |
Uża kwalunkwe data ta' skadenza futura u kwalunkwe CVC ta' 3 ċifri.
App Demo
App demo bbażata fuq Docker hija inkluża fir-repożitorju ta' GitHub għall-ittestjar tal-flusso sħiħ tal-ħlas:
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 --buildIftaħ http://localhost:3000 biex tara l-paġna demo tal-checkout.
Appoġġ
Għandek bżonn l-għajnuna? Ikkuntattja t-tim tal-appoġġ tagħna fuq support@costplus.io.