Node.js / TypeScript

Επίσημο Node.js/TypeScript SDK για την πύλη πληρωμών Cost+. Απλοποιεί τη ροή ανακατεύθυνσης HPP (Φιλοξενούμενη Σελίδα Πληρωμής), την υπογραφή HMAC payload και την επαλήθευση webhook.

Χαρακτηριστικά

Μηδέν εξαρτήσεις — χρησιμοποιεί μόνο τα ενσωματωμένα crypto και fetch του Node.js
Πλήρεις τύποι TypeScript με declaration maps
Δημιουργία υπογραφής HMAC-SHA256 και επαλήθευση σταθερού χρόνου
Αυτόματη αντιστοίχιση snake_case/camelCase μεταξύ API και SDK
Ανάλυση webhook + επαλήθευση παραγγελίας μέσω API
Δοκιμασμένο σε Node.js 18, 20 και 22

Απαιτήσεις

Node.js 18 ή νεότερο (χρησιμοποιεί ενσωματωμένο fetch)
Λογαριασμός εμπόρου Cost+ — dashboard.costplus.io

Εγκατάσταση

npm install nopayn-node-sdk

Γρήγορη Εκκίνηση

1. Αρχικοποίηση του Client

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. Δημιουργία Πληρωμής και Ανακατεύθυνση στο 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 UUID

3. Διαχείριση του 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

`new NoPaynClient(config)`

Παράμετρος	Τύπος	Απαιτούμενη	Προεπιλογή
`apiKey`	`string`	Ναι	—
`merchantId`	`string`	Ναι	—
`baseUrl`	`string`	Όχι	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Δημιουργεί παραγγελία μέσω POST /v1/orders/.

Παράμετρος	Τύπος	Απαιτούμενη	Περιγραφή
`amount`	`number`	Ναι	Ποσό στη μικρότερη μονάδα νομίσματος (λεπτά)
`currency`	`string`	Ναι	Κωδικός ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Όχι	Η εσωτερική αναφορά παραγγελίας σας
`description`	`string`	Όχι	Περιγραφή παραγγελίας
`returnUrl`	`string`	Όχι	Ανακατεύθυνση μετά από επιτυχή πληρωμή
`failureUrl`	`string`	Όχι	Ανακατεύθυνση σε ακύρωση/λήξη/σφάλμα
`webhookUrl`	`string`	Όχι	Ασύγχρονες ειδοποιήσεις αλλαγής κατάστασης
`locale`	`string`	Όχι	Γλώσσα HPP (`en-GB`, `de-DE`, `nl-NL`, κ.λπ.)
`paymentMethods`	`PaymentMethod[]`	Όχι	Φιλτράρισμα μεθόδων HPP
`expirationPeriod`	`string`	Όχι	Διάρκεια ISO 8601 (`PT30M`)

Διαθέσιμες μέθοδοι πληρωμής: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId)`

Ανακτά λεπτομέρειες παραγγελίας μέσω GET /v1/orders/{id}/.

`client.createRefund(orderId, amount, description?)`

Εκδίδει πλήρη ή μερική επιστροφή χρημάτων μέσω POST /v1/orders/{id}/refunds/.

`client.generatePaymentUrl(params)`

Μέθοδος ευκολίας που δημιουργεί παραγγελία και επιστρέφει:

{
  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)`

Δημιουργεί υπογραφή HMAC-SHA256 σε hex. Το κανονικό μήνυμα είναι ${amount}:${currency}:${orderId}, υπογεγραμμένο με το κλειδί API.

`client.verifySignature(amount, currency, orderId, signature)`

Επαλήθευση σταθερού χρόνου υπογραφής HMAC-SHA256. Επιστρέφει true αν είναι έγκυρη.

`client.verifyWebhook(rawBody)`

Αναλύει το σώμα webhook, στη συνέχεια καλεί GET /v1/orders/{id}/ για επαλήθευση πραγματικής κατάστασης. Επιστρέφει:

{
  orderId: string;
  order: Order;     // Verified via API
  isFinal: boolean; // true for completed/cancelled/expired/error
}

`client.parseWebhookBody(rawBody)`

Αναλύει και επικυρώνει σώμα webhook χωρίς κλήση API.

Αυτόνομα Εργαλεία HMAC

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);

Διαχείριση Σφαλμάτων

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
  }
}

Καταστάσεις Παραγγελίας

Κατάσταση	Τελική;	Περιγραφή
`new`	Όχι	Η παραγγελία δημιουργήθηκε
`processing`	Όχι	Πληρωμή σε εξέλιξη
`completed`	Ναι	Η πληρωμή ήταν επιτυχής — παραδώστε τα αγαθά
`cancelled`	Ναι	Η πληρωμή ακυρώθηκε από τον πελάτη
`expired`	Ναι	Ο σύνδεσμος πληρωμής έληξε
`error`	Ναι	Τεχνική αποτυχία

Βέλτιστες Πρακτικές Webhook

Πάντα επαληθεύετε μέσω API — το payload webhook περιέχει μόνο το αναγνωριστικό παραγγελίας, ποτέ την κατάσταση. Η μέθοδος verifyWebhook() του SDK το κάνει αυτόματα.
Επιστρέψτε HTTP 200 για επιβεβαίωση λήψης. Οποιοσδήποτε άλλος κωδικός ενεργοποιεί έως 10 επαναπροσπάθειες (2 λεπτά μεταξύ τους).
Υλοποιήστε εφεδρικό poller — για παραγγελίες παλαιότερες από 10 λεπτά που δεν έχουν φτάσει σε τελική κατάσταση, κάντε polling getOrder() ως δίχτυ ασφαλείας.
Να είστε idempotent — μπορεί να λάβετε το ίδιο webhook πολλές φορές.

Δοκιμαστικές Κάρτες

Χρησιμοποιήστε αυτές τις κάρτες στη δοκιμαστική λειτουργία Cost+ (ιστοσελίδα sandbox):

Κάρτα	Αριθμός	Σημειώσεις
Visa (επιτυχία)	`4111 1111 1111 1111`	Οποιοδήποτε CVV
Mastercard (επιτυχία)	`5544 3300 0003 7`	Οποιοδήποτε CVV
Visa (απόρριψη)	`4111 1111 1111 1105`	Do Not Honor
Visa (ανεπαρκές υπόλοιπο)	`4111 1111 1111 1151`	Insufficient Funds

Χρησιμοποιήστε οποιαδήποτε μελλοντική ημερομηνία λήξης και οποιοδήποτε 3ψήφιο CVC.

Εφαρμογή Επίδειξης

Μια εφαρμογή επίδειξης βασισμένη σε Docker περιλαμβάνεται στο αποθετήριο GitHub για δοκιμή πλήρους ροής πληρωμής:

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 --build

Ανοίξτε http://localhost:3000 για να δείτε τη σελίδα checkout επίδειξης.

Υποστήριξη

Χρειάζεστε βοήθεια; Επικοινωνήστε με την ομάδα υποστήριξης στο support@costplus.io.

On this page