Node.js / TypeScript

Opinber Node.js/TypeScript SDK fyrir Cost+ greiðslugáttina. Einfaldar HPP (Hýst greiðslusíða) tilvísunarflæði, HMAC farmundirritun og staðfestingu á vefhook.

Eiginleikar

Núll ósjálfstæði — notar aðeins innbyggða Node.js crypto og fetch
Fullar TypeScript tegundir með yfirlýsingakortum
HMAC-SHA256 undirskriftargerð og sannprófun á stöðugum tíma
Sjálfvirk Snake_case/camelCase kortlagning á milli API og SDK
Webhook þáttun + API byggt á pöntunarstaðfestingu
Prófað á Node.js 18, 20 og 22

Kröfur

Node.js 18 eða nýrri (notar innbyggða fetch)
Kostnaðar+ sölureikningur — dashboard.costplus.io

Uppsetning

npm install nopayn-node-sdk

Fljótleg byrjun

1. Frumstilla viðskiptavininn

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. Búðu til greiðslu og sendu til 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. Meðhöndlaðu vefkrókinn

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 Tilvísun

`new NoPaynClient(config)`

Parameter	Tegund	Áskilið	Sjálfgefið
`apiKey`	`string`	Já	—
`merchantId`	`string`	Já	—
`baseUrl`	`string`	Nei	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Býr til pöntun í gegnum POST /v1/orders/.

Parameter	Tegund	Áskilið	Lýsing
`amount`	`number`	Já	Upphæð í ISO 4217 minnieiningu gjaldmiðilsins (til dæmis sent fyrir EUR)
`currency`	`string`	Já	ISO 4217 kóði (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nei	Innri pöntunartilvísun þín
`description`	`string`	Nei	Lýsing á pöntun
`returnUrl`	`string`	Nei	Tilvísun eftir vel heppnaða greiðslu
`failureUrl`	`string`	Nei	Tilvísun við hætt við/rennur út/villu
`webhookUrl`	`string`	Nei	Ósamstilltur tilkynningar um stöðubreytingar
`locale`	`string`	Nei	HPP tungumál (`en-GB`, `de-DE`, `nl-NL`, osfrv.)
`paymentMethods`	`PaymentMethod[]`	Nei	Sía HPP aðferðir
`expirationPeriod`	`string`	Nei	ISO 8601 tímalengd (`PT30M`)

Greiðsluaðferðir í boði: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId)`

Sækir pöntunarupplýsingar í gegnum GET /v1/orders/{id}/.

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

Gefur út fulla eða hluta endurgreiðslu í gegnum POST /v1/orders/{id}/refunds/.

`client.generatePaymentUrl(params)`

Þægindaaðferð sem býr til pöntun og skilar:

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

Myndar HMAC-SHA256 hex undirskrift. Hin kanónísku skilaboð eru ${amount}:${currency}:${orderId}, undirrituð með API lyklinum.

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

Stöðug staðfesting á HMAC-SHA256 undirskrift. Skilar true ef það er gilt.

`client.verifyWebhook(rawBody)`

Þýðir meginmál vefkróksins og hringir síðan í GET /v1/orders/{id}/ til að staðfesta raunverulega stöðu. Skilar:

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

`client.parseWebhookBody(rawBody)`

Málar og staðfestir vefhook meginmál án þess að hringja í API.

Sjálfstæð HMAC tól

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

Villumeðferð

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

Pöntunarstöður

Staða	Úrslitaleikur?	Lýsing
`new`	Nei	Pöntun búin til
`processing`	Nei	Greiðsla í gangi
`completed`	Já	Greiðsla tókst - afhenda vörurnar
`cancelled`	Já	Greiðsla felld niður af viðskiptavinum
`expired`	Já	Greiðslutengillinn rann út á tíma
`error`	Já	Tæknileg bilun

Bestu starfsvenjur Webhook

Staðfestu alltaf í gegnum API — hleðslutækið inniheldur aðeins pöntunarauðkenni, aldrei stöðuna. verifyWebhook() á SDK gerir þetta sjálfkrafa.
** Skilaðu HTTP 200** til að staðfesta móttöku. Allir aðrir kóðar kalla fram allt að 10 endurtilraunir (2 mínútna millibili).
Taka í notkun varakönnun — fyrir pantanir eldri en 10 mínútur sem hafa ekki náð endanlega stöðu skaltu skoða getOrder() sem öryggisnet.
Vertu sjálfráða — þú gætir fengið sama vefhook margoft.

Prófakort

Notaðu þessi kort í Cost+ prófunarham (sandkassavefsíða):

Kort	Númer	Skýringar
Visa (árangur)	`4111 1111 1111 1111`	Hvaða CVV sem er
Mastercard (árangur)	`5544 3300 0003 7`	Hvaða CVV sem er
Visa (hafnað)	`4111 1111 1111 1105`	Heiðra ekki
Visa (ófullnægjandi fjármunir)	`4111 1111 1111 1151`	Ófullnægjandi fjármunir

Notaðu hvaða fyrningardagsetningu sem er í framtíðinni og hvaða þriggja stafa CVC sem er.

Demo app

Sýningarforrit sem byggir á Docker er innifalið í GitHub geymslunni til að prófa allt greiðsluflæðið:

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

Opnaðu http://localhost:3000 til að sjá útskráningarsíðu kynningar.

Stuðningur

Þarftu aðstoð? Hafðu samband við þjónustudeild okkar á support@costplus.io.

Node.js / TypeScript

On this page