Node.js / TypeScript

Virallinen Node.js/TypeScript SDK Cost+-maksuportille. Yksinkertaistaa HPP (isännöidyn maksusivun) uudelleenohjausta, HMAC-allekirjoitusta ja webhook-vahvistusta.

Ominaisuudet

Nolla riippuvuutta — käyttää vain Node.js:n sisäänrakennettuja crypto- ja fetch-moduuleja
Täydet TypeScript-tyypit ja deklaraatiokartat
HMAC-SHA256-allekirjoituksen luonti ja vakioaikainen vahvistus
Automaattinen snake_case/camelCase-muunnos API:n ja SDK:n välillä
Webhook-jäsennys + API-pohjainen tilauksen vahvistus
Testattu Node.js 18-, 20- ja 22-versioilla

Vaatimukset

Node.js 18 tai uudempi (käyttää sisäänrakennettua fetch-funktiota)
Cost+-kauppiastili — dashboard.costplus.io

Asennus

npm install nopayn-node-sdk

Pikaopas

1. Alusta asiakas

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. Luo maksu ja ohjaa HPP:hen

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. Käsittele 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-viite

`new NoPaynClient(config)`

Parametri	Tyyppi	Pakollinen	Oletus
`apiKey`	`string`	Kyllä	—
`merchantId`	`string`	Kyllä	—
`baseUrl`	`string`	Ei	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Luo tilauksen kutsulla POST /v1/orders/.

Parametri	Tyyppi	Pakollinen	Kuvaus
`amount`	`number`	Kyllä	Summa pienimmässä valuuttayksikössä (senteissä)
`currency`	`string`	Kyllä	ISO 4217 -koodi (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Ei	Oma sisäinen tilausviitteesi
`description`	`string`	Ei	Tilauksen kuvaus
`returnUrl`	`string`	Ei	Uudelleenohjaus onnistuneen maksun jälkeen
`failureUrl`	`string`	Ei	Uudelleenohjaus peruutuksen/vanhenemisen/virheen yhteydessä
`webhookUrl`	`string`	Ei	Asynkroniset tilanmuutosilmoitukset
`locale`	`string`	Ei	HPP:n kieli (`en-GB`, `de-DE`, `nl-NL` jne.)
`paymentMethods`	`PaymentMethod[]`	Ei	Suodata HPP:n maksutapoja
`expirationPeriod`	`string`	Ei	ISO 8601 -kesto (`PT30M`)

Käytettävissä olevat maksutavat: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId)`

Hakee tilauksen tiedot kutsulla GET /v1/orders/{id}/.

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

Tekee täyden tai osittaisen palautuksen kutsulla POST /v1/orders/{id}/refunds/.

`client.generatePaymentUrl(params)`

Apumetodi, joka luo tilauksen ja palauttaa:

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

Luo HMAC-SHA256 hex-allekirjoituksen. Kanoninen viesti on ${amount}:${currency}:${orderId}, allekirjoitettu API-avaimella.

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

Vakioaikainen HMAC-SHA256-allekirjoituksen vahvistus. Palauttaa true, jos kelvollinen.

`client.verifyWebhook(rawBody)`

Jäsentää webhook-rungon ja kutsuu sitten GET /v1/orders/{id}/ varmistaakseen todellisen tilan. Palauttaa:

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

`client.parseWebhookBody(rawBody)`

Jäsentää ja validoi webhook-rungon kutsumatta API:a.

Erilliset HMAC-apufunktiot

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

Virheenkäsittely

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

Tilausten tilat

Tila	Lopullinen?	Kuvaus
`new`	Ei	Tilaus luotu
`processing`	Ei	Maksu käynnissä
`completed`	Kyllä	Maksu onnistui — toimita tavarat
`cancelled`	Kyllä	Asiakas peruutti maksun
`expired`	Kyllä	Maksulinkki vanheni
`error`	Kyllä	Tekninen virhe

Webhook-parhaat käytännöt

Vahvista aina API:n kautta — webhook-data sisältää vain tilauksen tunnisteen, ei koskaan tilaa. SDK:n verifyWebhook() tekee tämän automaattisesti.
Palauta HTTP 200 kuittauksena. Mikä tahansa muu koodi käynnistää enintään 10 uudelleenyritystä (2 minuutin välein).
Toteuta varapolleri — yli 10 minuuttia vanhoille tilauksille, jotka eivät ole saavuttaneet lopullista tilaa, pollaa getOrder() turvavarana.
Ole idempotentti — saatat vastaanottaa saman webhookin useita kertoja.

Testikortit

Käytä näitä kortteja Cost+:n testitilassa (sandbox-verkkosivusto):

Kortti	Numero	Huomautukset
Visa (onnistunut)	`4111 1111 1111 1111`	Mikä tahansa CVV
Mastercard (onnistunut)	`5544 3300 0003 7`	Mikä tahansa CVV
Visa (hylätty)	`4111 1111 1111 1105`	Do Not Honor
Visa (riittämätön kate)	`4111 1111 1111 1151`	Insufficient Funds

Käytä mitä tahansa tulevaa voimassaolopäivää ja mitä tahansa 3-numeroista CVC:tä.

Demosovellus

Docker-pohjainen demosovellus sisältyy GitHub-tietovarastoon täyden maksukulun testaamiseksi:

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

Avaa http://localhost:3000 nähdäksesi demokaasan.

Tuki

Tarvitsetko apua? Ota yhteyttä tukitiimiimme osoitteessa support@costplus.io.

On this page