React SDK

React 18+   TypeScript

Hooks and components built on top of @neptune.fintech/astro-sdk. Works with Next.js, Vite, CRA, and any React 18+ app.

Install

npm install @neptune.fintech/astro-react @neptune.fintech/astro-sdk

Setup — AstroProvider

Wrap your app (or checkout subtree) with AstroProvider:

// app/layout.tsx (Next.js) or main.tsx (Vite)
import { AstroProvider } from '@neptune.fintech/astro-react'
import { createClient } from '@neptune.fintech/astro-sdk'

const astro = createClient({
  baseUrl: 'https://astro.neptune.ly/api/v1',
  merchantKey: process.env.NEXT_PUBLIC_ASTRO_KEY  // ⚠️ only if this is a public read-only key
})

export default function RootLayout({ children }) {
  return (
    <AstroProvider client={astro}>
      {children}
    </AstroProvider>
  )
}

Session creation must be server-side

Use server actions (Next.js), an API route, or your own backend to create payment sessions. Never expose your merchant API key in client-side bundles.

usePaymentSession

import { usePaymentSession } from '@neptune.fintech/astro-react'

function PayButton({ orderId }: { orderId: string }) {
  const { session, loading, error, create } = usePaymentSession()

  const handlePay = async () => {
    // Call your backend to create a session, then pass the session_id here
    const { session_id } = await fetch('/api/checkout', {
      method: 'POST',
      body: JSON.stringify({ reference: orderId })
    }).then(r => r.json())

    await create(session_id)   // loads session state into hook
  }

  if (loading) return <Spinner />
  if (error) return <p>Error: {error.message}</p>
  if (session?.status === 'COMPLETED') return <p>✅ Payment complete!</p>

  return <button onClick={handlePay}>Pay Now</button>
}

useAliasResolve

import { useAliasResolve } from '@neptune.fintech/astro-react'

function AliasInput() {
  const { resolve, result, loading, error } = useAliasResolve()

  return (
    <>
      <input
        placeholder="Enter alias (e.g. mtellesy)"
        onBlur={(e) => resolve(e.target.value)}
      />
      {loading && <span>Looking up...</span>}
      {result && (
        <p>
          Sends to: <strong>{result.bankHandle}</strong> — {result.iban.slice(0, 8)}...
        </p>
      )}
      {error && <p style={{ color: 'red' }}>{error.message}</p>}
    </>
  )
}

useOpenBankingConsent

import { useOpenBankingConsent } from '@neptune.fintech/astro-react'

function ConnectBank() {
  const { consent, loading, initiate, exchange, tokens } = useOpenBankingConsent()

  const connect = async () => {
    await initiate({
      bankHandle: 'andalus',
      scopes: ['accounts:read', 'transactions:read'],
      redirectUri: window.location.origin + '/ob/callback'
    })
    // User is redirected to consent.consentUrl — handle callback separately
  }

  return (
    <button onClick={connect} disabled={loading}>
      Connect Andalus Bank
    </button>
  )
}

CheckoutButton

Drop-in button that opens the Astro checkout modal:

import { CheckoutButton } from '@neptune.fintech/astro-react'

function ProductPage() {
  const getSessionId = async () => {
    const r = await fetch('/api/checkout', { method: 'POST', body: JSON.stringify({ amount: 50000 }) })
    const { session_id } = await r.json()
    return session_id
  }

  return (
    <CheckoutButton
      getSessionId={getSessionId}
      gatewayUrl="https://astro.neptune.ly"
      onSuccess={(r) => console.log('Paid!', r)}
      onFailure={(e) => console.error(e)}
    >
      Pay 500 LYD
    </CheckoutButton>
  )
}

Source

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