dpay Node.js SDK

Oficjalna biblioteka Node.js do integracji z API płatności dpay.pl.

Wymagania

• Node.js 20 lub nowszy
• Zero zależności runtime
• Typy TypeScript dołączone do paczki - osobny pakiet @types/* nie jest potrzebny

Instalacja

npm install @dpayglobal/dpay-node-sdk

Paczka jest budowana równolegle jako ESM i CJS, więc import i require działają od razu, bez dodatkowej konfiguracji.

Szybki start

import { DPayClient, Money, TransactionType } from '@dpayglobal/dpay-node-sdk'

const dpay = new DPayClient({
  service: 'nazwa_serwisu',
  secretHash: 'twoj_secret_hash',
})

const payment = await dpay.payments.register({
  amount: Money.pln(1050),
  transactionType: TransactionType.TRANSFERS,
  urls: {
    success: 'https://twojsklep.pl/sukces',
    fail: 'https://twojsklep.pl/blad',
    ipn: 'https://twojsklep.pl/ipn',
  },
  description: 'Zamówienie #1234',
  custom: 'order-1234',
})

if (payment.redirectUrl !== null) {
  // przekieruj płatnika pod payment.redirectUrl
}

Obsługa IPN

dpay uznaje IPN za dostarczony wyłącznie, gdy body odpowiedzi to dokładnie OK. Kod HTTP nie jest sprawdzany. Zawsze porównaj kwotę z własnym zamówieniem - payload IPN nie niesie waluty, więc event.amount to surowy string dziesiętny.

Podpis liczy się z surowych bajtów żądania. express.json() konsumuje strumień, więc trasa IPN musi być zamontowana przed nim:

import express from 'express'
import { DPayClient, IPN_ACK, SignatureVerificationError } from '@dpayglobal/dpay-node-sdk'

const app = express()
const dpay = new DPayClient({ service: 'moj_sklep', secretHash: process.env.DPAY_SECRET_HASH })

app.post('/ipn', express.raw({ type: '*/*' }), async (req, res) => {
  let event
  try {
    event = await dpay.ipn.constructEventFromRequest(req.body)
  } catch (error) {
    if (error instanceof SignatureVerificationError) return res.status(400).send('Invalid signature')
    throw error
  }

  if (event.isTransfer || event.isCapture) {
    await oznaczZamowienieJakoOplacone(event.id, event.amount)
  }

  res.send(IPN_ACK)
})

app.use(express.json())

W Next.js (App Router) i Hono przekaż obiekt Request bezpośrednio:

export async function POST(request) {
  const event = await dpay.ipn.constructEventFromRequest(request)
  return new Response(IPN_ACK)
}

Zwroty

import { Money } from '@dpayglobal/dpay-node-sdk'

await dpay.refunds.create({ transactionId: 'identyfikator-transakcji' })
await dpay.refunds.create({
  transactionId: 'identyfikator-transakcji',
  amount: Money.pln(500),
  reason: 'reklamacja',
})

const availability = await dpay.refunds.checkAvailability({ transactionId: 'identyfikator-transakcji' })
if (availability.isAvailable) {
  // ...
}

Szczegóły transakcji i banki

const transaction = await dpay.payments.details('identyfikator-transakcji')
transaction.isPaid
transaction.availableRefundAmount.toDecimal()
transaction.refunds

const banks = await dpay.banks.forService()

Karty S2S

import { CardData, CardEncryptor } from '@dpayglobal/dpay-node-sdk'

const publicKey = await dpay.cards.publicKey()
const encryptedCardData = new CardEncryptor().encrypt(
  new CardData({ pan: '4111111111111111', cvv: '123', expiry: '12/28' }),
  transactionId,
  publicKey,
)

// deviceInfo to fingerprint przeglądarki płatnika, patrz DeviceInfoParams
const result = await dpay.cards.payOtp(transactionId, { deviceInfo, encryptedCardData })

if (result.requiresThreeDsForm) {
  // zwróć result.threeDsFormHtml jako odpowiedź HTML
}
if (result.hasDccOffer) {
  const offer = result.dccOffer
}

Klucz publiczny jest rotowany - pobieraj go przed każdą próbą płatności.

Obsługa błędów

Wszystkie wyjątki SDK dziedziczą po DPayError.

import { ApiError, DPayError, InvalidRequestError, TransportError } from '@dpayglobal/dpay-node-sdk'

try {
  const payment = await dpay.payments.register(params)
} catch (error) {
  if (error instanceof InvalidRequestError) {
    error.fieldErrors
  } else if (error instanceof ApiError) {
    error.httpStatus
    error.errorCode
  } else if (error instanceof TransportError) {
    // błąd sieci - status płatności nieznany, użyj payments.details()
  } else {
    throw error
  }
}

Każdy błąd niesie też pole type (na przykład 'invalid_request_error') - stabilny dyskryminator do użycia w switch, gdy instanceof zawodzi.

| Wyjątek | Kiedy | |---|---| | AuthenticationError | 401 - niepoprawny checksum | | InvalidRequestError | 400, 422 | | AccessDeniedError | 403 | | NotFoundError | 404 | | RateLimitError | 429 | | ApiServerError | 5xx | | PaymentRejectedError | rejestracja odrzucona przy HTTP 200 | | CardPaymentError | płatność kartą odrzucona przy HTTP 200 | | SignatureVerificationError | niepoprawny podpis IPN | | CardEncryptionError | szyfrowanie danych karty nie powiodło się | | TransportError | awaria sieci, timeout lub przerwanie przez signal | | DPayValueError | niepoprawny argument - rzucany przed jakimkolwiek wywołaniem sieciowym |

Konfiguracja

| Opcja | Typ | Opis | |---|---|---| | service | string | Nazwa Punktu Płatności z panel.dpay.pl (wymagane) | | secretHash | string | Klucz Secret Hash (wymagane) | | timeout | number | Timeout HTTP w milisekundach (domyślnie 30000) | | httpClient | HttpClient | Własny transport (proxy, retry, testy) | | baseUrls | Record<string, string> | Nadpisanie hostów apiPayments, panel, gateway | | onRequest | (context) => void | Wywoływane przed każdym żądaniem - checksum i dane karty są już ukryte | | onResponse | (context) => void | Wywoływane po każdej odpowiedzi, która dotarła do SDK |

Anulowanie i timeouty

Każda metoda serwisu przyjmuje opcjonalny, ostatni argument { signal?, timeout? }.

const controller = new AbortController()
setTimeout(() => controller.abort(), 5000)

await dpay.payments.details('identyfikator-transakcji', { signal: controller.signal })

Timeout jest w milisekundach i domyślnie wynosi 30000 (patrz konfiguracja). Wartość podana per wywołanie nadpisuje go tylko dla tego jednego wywołania:

await dpay.payments.details('identyfikator-transakcji', { timeout: 5000 })

signal i timeout są łączone - żądanie kończy się na to, co nastąpi pierwsze. Przerwanie i przekroczenie czasu mapują się na TransportError z zachowanym cause.

Testowanie integracji

import { DPayClient, Money, TransactionType } from '@dpayglobal/dpay-node-sdk'
import { MockHttpClient } from '@dpayglobal/dpay-node-sdk/testing'
import assert from 'node:assert/strict'

const transport = new MockHttpClient()
transport.queueJson(200, { transactionId: 'tx-1', msg: 'https://secure.dpay.pl/pay/1' })

const dpay = new DPayClient({ service: 'test', secretHash: 'test', httpClient: transport })
const payment = await dpay.payments.register({
  amount: Money.pln(1050),
  transactionType: TransactionType.TRANSFERS,
  urls: {
    success: 'https://twojsklep.pl/sukces',
    fail: 'https://twojsklep.pl/blad',
    ipn: 'https://twojsklep.pl/ipn',
  },
})

assert.equal(transport.lastRequestBody.value, '10.50')

Licencja

Apache-2.0