TypeScript / Node.js SDK

TypeScript   Node.js 18+

Server-side SDK for Node.js, Deno, and Bun. Tree-shakeable ESM + CommonJS dual build.

Install

npm install @neptune.fintech/astro-sdk
# or
pnpm add @neptune.fintech/astro-sdk
# or
yarn add @neptune.fintech/astro-sdk

Quick Start

import { createClient } from '@neptune.fintech/astro-sdk'

const astro = createClient({
  baseUrl: 'https://astro.neptune.ly/api/v1',
  merchantKey: process.env.ASTRO_MERCHANT_KEY
})

// Create a payment session
const session = await astro.payments.createSession({
  amount: 50_000,     // 50.000 LYD
  currency: 'LYD',
  destination: { type: 'alias', value: 'mtellesy' },
  reference: 'order_1042',
  redirectUrl: 'https://myapp.com/checkout/result',
  webhookUrl: 'https://myapp.com/webhooks/astro'
})

console.log('Redirect customer to:', session.checkoutUrl)

Modules

astro.payments

// Create session
const session = await astro.payments.createSession({
  amount, currency, destination, reference, redirectUrl, webhookUrl
})

// Get session status
const updated = await astro.payments.getSession(session.session_id)
console.log(updated.status) // 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED'

// List sessions
const { sessions, pagination } = await astro.payments.listSessions({ status: 'COMPLETED' })

// Cancel
await astro.payments.cancelSession(session.session_id)

// Mandates
const mandate = await astro.payments.createMandate({
  customerAlias: 'mtellesy',
  amount: 5_000,
  currency: 'LYD',
  interval: 'monthly',
  description: 'Monthly subscription',
  startDate: '2026-05-01'
})

astro.alias

// Resolve an alias to IBAN + bank
const resolved = await astro.alias.resolve('mtellesy')
// { nptHandle: 'mtellesy', iban: 'LY83...', bankHandle: 'andalus' }

// Get alias profile
const profile = await astro.alias.getProfile('mtellesy')

// Get linked accounts
const { accounts } = await astro.alias.getAccounts('mtellesy')

astro.openBanking

// Create consent
const consent = await astro.openBanking.createConsent({
  bankHandle: 'andalus',
  scopes: ['accounts:read', 'transactions:read'],
  redirectUri: 'https://myapp.com/ob/callback',
  state: crypto.randomUUID(),
  codeChallenge: pkce.challenge,
  codeChallengeMethod: 'S256'
})
// Redirect user to consent.consentUrl

// Exchange code after redirect
const tokens = await astro.openBanking.exchangeToken({
  code: req.query.code,
  redirectUri: '...',
  consentId: consent.consentId,
  codeVerifier: pkce.verifier
})

// Fetch data
const accounts = await astro.openBanking.getAccounts(tokens.accessToken, consent.consentId)
const txns = await astro.openBanking.getTransactions(tokens.accessToken, consent.consentId, accounts[0].accountId)

astro.webhooks — WebhookReceiver

import { WebhookReceiver } from '@neptune.fintech/astro-sdk'

const receiver = new WebhookReceiver({ secret: process.env.ASTRO_WEBHOOK_SECRET! })

receiver.on('payment.completed', (event) => {
  const { reference, amount, settlement_type } = event.data
  console.log(`Order ${reference} paid via ${settlement_type}`)
  db.orders.markPaid(reference)
})

receiver.on('payment.failed', (event) => {
  db.orders.markFailed(event.data.reference)
})

// Express
app.post('/webhooks/astro', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.headers['x-openwave-signature'] as string
  if (!receiver.verify(req.body.toString(), sig)) return res.sendStatus(401)
  receiver.dispatch(JSON.parse(req.body))
  res.sendStatus(200)
})

Source

packages/astro-js/ in the neptune-astro repo.