Node.js / TypeScript
SDK oifigiúil Node.js do gheata íocaíochta Cost+
SDK oifigiúil Node.js/TypeScript do gheata íocaíochta Cost+. Simpliú an tsreabha atreoraithe HPP (Leathanach Íocaíochta Óstáilte), síniú sonraí HMAC, agus fíorú webhook.
Gnéithe
- Nialas spleáchas -- ní úsáideann sé ach
cryptoagusfetchionsuite Node.js - Cineálacha TypeScript iomlána le léarscáileanna dearbhaithe
- Giniúint sínithe HMAC-SHA256 agus fíorú ama-leanúnaigh
- Mapáil uathoibríoch snake_case/camelCase idir an API agus SDK
- Parsáil webhook + fíorú ordaithe bunaithe ar API
- Tástáilte ar fud Node.js 18, 20, agus 22
Riachtanais
- Node.js 18 nó níos déanaí (úsáideann sé
fetchionsuite) - Cuntas ceannaithe Cost+ -- dashboard.costplus.io
Suiteáil
npm install nopayn-node-sdkMearthosnú
1. Túsaigh an Cliant
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. Cruthaigh Íocaíocht agus Atreorófar chuig an 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 UUID3. Láimhseáil an 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);
});Tagairt API
new NoPaynClient(config)
| Paraiméadar | Cineál | Riachtanach | Réamhshocrú |
|---|---|---|---|
apiKey | string | Tá | -- |
merchantId | string | Tá | -- |
baseUrl | string | Níl | https://api.nopayn.co.uk |
client.createOrder(params)
Cruthaíonn ordú tríd an POST /v1/orders/.
| Paraiméadar | Cineál | Riachtanach | Cur Síos |
|---|---|---|---|
amount | number | Tá | Méid i mionaonad ISO 4217 an airgeadra (mar shampla, cent le haghaidh EUR) |
currency | string | Tá | Cód ISO 4217 (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | string | Níl | Do thagairt inmheánach ordaithe |
description | string | Níl | Cur síos ar an ordú |
returnUrl | string | Níl | Atreorú tar éis íocaíochta rathúla |
failureUrl | string | Níl | Atreorú ar cheallú/éag/earráid |
webhookUrl | string | Níl | Fógraí athraithe stádais asincrónach |
locale | string | Níl | Teanga HPP (en-GB, de-DE, nl-NL, srl.) |
paymentMethods | PaymentMethod[] | Níl | Scag modhanna HPP |
expirationPeriod | string | Níl | Fad ISO 8601 (PT30M) |
Modhanna íocaíochta ar fáil: credit-card, apple-pay, google-pay, vipps-mobilepay
client.getOrder(orderId)
Faigheann sonraí ordaithe tríd an GET /v1/orders/{id}/.
client.createRefund(orderId, amount, description?)
Eisíonn aisíocaíocht iomlán nó pháirteach tríd an POST /v1/orders/{id}/refunds/.
client.generatePaymentUrl(params)
Modh áise a chruthaíonn ordú agus a sheolann ar ais:
{
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)
Gineann síniú HMAC-SHA256 hex. Is é an teachtaireacht chanónta ná ${amount}:${currency}:${orderId}, sínithe leis an eochair API.
client.verifySignature(amount, currency, orderId, signature)
Fíorú ama-leanúnaigh ar shíniú HMAC-SHA256. Seolann true ar ais má tá sé bailí.
client.verifyWebhook(rawBody)
Parsáileann corp an webhook, ansin glaonn GET /v1/orders/{id}/ chun an stádas iarbhír a fhíorú. Seolann ar ais:
{
orderId: string;
order: Order; // Verified via API
isFinal: boolean; // true for completed/cancelled/expired/error
}client.parseWebhookBody(rawBody)
Parsáileann agus bailíochtaíonn corp webhook gan an API a ghlaoch.
Fóntais HMAC Neamhspleácha
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);Láimhseáil Earráidí
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
}
}Stádais Ordaithe
| Stádas | Deiridh? | Cur Síos |
|---|---|---|
new | Níl | Ordú cruthaithe |
processing | Níl | Íocaíocht ar siúl |
completed | Tá | D'éirigh leis an íocaíocht -- seachaid na hearraí |
cancelled | Tá | Cheal an custaiméir an íocaíocht |
expired | Tá | D'éag an nasc íocaíochta |
error | Tá | Teip theicniúil |
Dea-Chleachtais Webhook
- Fíoraigh tríd an API i gcónaí -- ní bhíonn ach aitheantas an ordaithe sa sonraí webhook, ní an stádas riamh. Déanann
verifyWebhook()an SDK é seo go huathoibríoch. - Seol HTTP 200 ar ais chun fáiltiú a admháil. Spreagann aon chód eile suas le 10 n-atriail (2 nóiméad eatarthu).
- Cuir cúltaca pólaí i bhfeidhm -- d'orduithe atá níos sine ná 10 nóiméad nach bhfuil stádas deiridh bainte amach acu, pólail
getOrder()mar líontán sábháilteachta. - Bí idéimpotent -- d'fhéadfá an webhook céanna a fháil arís is arís eile.
Cártaí Tástála
Úsáid na cártaí seo i mód tástála Cost+ (suíomh gréasáin gaineamhchláir):
| Cárta | Uimhir | Nótaí |
|---|---|---|
| Visa (rath) | 4111 1111 1111 1111 | Aon CVV |
| Mastercard (rath) | 5544 3300 0003 7 | Aon CVV |
| Visa (diúltaithe) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (cistí neamhleor) | 4111 1111 1111 1151 | Insufficient Funds |
Úsáid aon dáta éaga amach anseo agus aon CVC 3 dhigit.
Aip Thaispeána
Tá aip thaispeána Docker-bhunaithe san áireamh sa stór GitHub chun an sreabhadh íocaíochta iomlán a thástáil:
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 --buildOscail http://localhost:3000 chun an leathanach seiceála amach taispeána a fheiceáil.
Tacaíocht
Cabhair ag teastáil? Déan teagmháil lenár bhfoireann tacaíochta ag support@costplus.io.