SablePay Developer Docs

// app/layout.tsx (Next.js App Router) or _app.tsx (Pages Router)
import { SablePay } from '@sablepay/react-sablepay-js';

SablePay.initialize({
  apiKey: process.env.NEXT_PUBLIC_SABLEPAY_API_KEY!,
  merchantId: process.env.NEXT_PUBLIC_SABLEPAY_MERCHANT_ID!,
  enableLogging: process.env.NODE_ENV === 'development',
});

import { PaymentButton } from '@sablepay/react-sablepay-js/react';

export default function CheckoutPage() {
  return (
    <PaymentButton
      amount={10.50}
      onSuccess={(status) => {
        console.log('Payment complete!', status.txHash);
      }}
      onError={(err) => {
        console.error('Payment failed:', err);
      }}
    />
  );
}

import { usePaymentFlow } from '@sablepay/react-sablepay-js/react';

export default function PaymentPage() {
  const { state, startPayment, cancel, qrDataUrl, error } = usePaymentFlow({
    onPaymentCompleted(status) {
      console.log('Done!', status.txHash);
    },
  });

  return (
    <div>
      {state.type === 'idle' && (
        <button onClick={() => startPayment(10.50)}>Pay $10.50</button>
      )}
      {state.type === 'creating' && <p>Creating payment...</p>}
      {state.type === 'awaiting' && qrDataUrl && (
        <div>
          <img src={qrDataUrl} alt="Scan to pay" width={300} height={300} />
          <p>Scan the QR code with your wallet</p>
        </div>
      )}
      {state.type === 'processing' && <p>Processing payment...</p>}
      {state.type === 'completed' && <p>Payment complete!</p>}
      {state.type === 'failed' && <p>{error}</p>}
      {state.type !== 'idle' && state.type !== 'completed' && (
        <button onClick={cancel}>Cancel</button>
      )}
    </div>
  );
}

// app/providers.tsx
'use client';
import { SablePayProvider } from '@sablepay/react-sablepay-js/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <SablePayProvider
      apiKey={process.env.NEXT_PUBLIC_SABLEPAY_API_KEY!}
      merchantId={process.env.NEXT_PUBLIC_SABLEPAY_MERCHANT_ID!}
    >
      {children}
    </SablePayProvider>
  );
}

// In any child component
import { useSablePay } from '@sablepay/react-sablepay-js/react';

function MyComponent() {
  const sdk = useSablePay();
  // sdk.createPayment(), sdk.getPaymentStatus(), etc.
}

// Initialize (call once)
SablePay.initialize({
  apiKey: 'sable_sk_sand_...',     // Required
  merchantId: 'uuid-here',         // Required
  baseUrl: '...',                   // Optional (auto-detected)
  enableLogging: true,              // Optional (default: false)
});

// Get instance
const sdk = SablePay.getInstance();

// Create a payment
const response = await sdk.createPayment({
  amount: 10.50,
  metadata: { orderId: 'ORD-123' },
});
// response.paymentId, response.paymentLink, response.status, etc.

// Get payment status
const status = await sdk.getPaymentStatus('payment-id');
// status.status, status.txHash, status.paidToken, etc.

// List payments
const payments = await sdk.listPayments(20, 0);

// Check environment
sdk.getEnvironment(); // 'sandbox' | 'production'

// Check if configured
sdk.isConfigured(); // boolean

// Create a payment flow
const flow = SablePay.createPaymentFlow();

// Release resources
SablePay.release();

const {
  state,           // PaymentFlowState
  startPayment,    // (amount, metadata?) => Promise<void>
  cancel,          // () => void
  isActive,        // boolean
  qrDataUrl,       // string | null
  paymentResponse, // CreatePaymentResponse | null
  paymentStatus,   // PaymentStatusResponse | null
  error,           // string | null
} = usePaymentFlow({
  onPaymentCreated: (response, qrUrl) => {},
  onStatusUpdate: (status) => {},
  onPaymentCompleted: (status) => {},
  onPaymentFailed: (error) => {},
  qrCodeConfig: { width: 400 },
  pollOptions: { intervalMs: 3000 },
});

const {
  createPayment,    // (request) => Promise<CreatePaymentResponse>
  getPaymentStatus, // (id) => Promise<PaymentStatusResponse>
  listPayments,     // (limit?, offset?) => Promise<PaymentStatusResponse[]>
  loading,          // boolean
  error,            // Error | null
  clearError,       // () => void
} = usePayment();

const sdk = useSablePay();

<PaymentButton
  amount={10.50}
  label="Checkout"
  metadata={{ orderId: 'ORD-123' }}
  onSuccess={(status) => {}}
  onError={(message) => {}}
  onCancel={() => {}}
  className="my-button"
  disabled={false}
/>

<PaymentQrCode
  paymentResponse={response}
  // Or: paymentLink="https://pay.sablepay.io/..."
  config={{ width: 400, height: 400 }}
  onGenerated={(dataUrl) => {}}
  onError={(error) => {}}
/>

<PaymentStatus
  paymentId="payment-id"
  autoPoll={true}
  pollInterval={3000}
  onStatusChange={(status) => {}}
  onTerminal={(status) => {}}
/>

{/* Or with custom rendering */}
<PaymentStatus paymentId="payment-id">
  {(status, loading, error) => (
    <div>{status?.status}</div>
  )}
</PaymentStatus>

interface CreatePaymentRequest {
  amount: number;                         // USD amount (0.01 - 1,000,000)
  items?: PaymentItem[];                  // Optional line items
  metadata?: Record<string, string>;      // Optional metadata
}

interface CreatePaymentResponse {
  paymentId: string;
  status: string;
  amount: number;
  acceptedTokens: string;
  paymentLink: string | null;
  businessName: string;
  expiresAt: string | null;
  createdAt: string;
}

interface PaymentStatusResponse {
  paymentId: string;
  amount: number;
  status: string;           // PENDING | COMPLETED | FAILED | EXPIRED
  txHash?: string | null;   // Blockchain TX hash
  paidToken?: string | null;
  paidNetwork?: string | null;
  paidAmount?: number | null;
  metadata?: Record<string, unknown> | null;
  createdAt: string;
  completedAt?: string | null;
  expiresAt?: string | null;
}

import { ApiException } from '@sablepay/react-sablepay-js';

try {
  await sdk.createPayment({ amount: 10.50 });
} catch (error) {
  if (error instanceof ApiException) {
    console.log(error.statusCode);    // 400, 401, 429, 500, etc.
    console.log(error.message);       // Error message
    console.log(error.requestId);     // For debugging
    console.log(error.isRetryable);   // true for 5xx and 429
    console.log(error.isAuthError);   // true for 401
    console.log(error.retryAfter);    // Seconds to wait (for 429)
  }
}

import { QrCodeGenerator } from '@sablepay/react-sablepay-js';

const generator = new QrCodeGenerator({ width: 400, height: 400 });

// From payment response
const dataUrl = await generator.generatePaymentQr(response);

// From any text
const qr = await generator.generate('https://example.com');

// As SVG
const svg = await generator.generateSvg('https://example.com');

import { PaymentPoller } from '@sablepay/react-sablepay-js';

const poller = new PaymentPoller((id) => sdk.getPaymentStatus(id));

// Callback-based
poller.startPolling('payment-id', (result) => {
  if (result.success) console.log(result.data.status);
});
poller.stopPolling();

// Promise-based (awaits terminal state)
const finalStatus = await poller.pollUntilTerminal('payment-id');

NEXT_PUBLIC_SABLEPAY_API_KEY=sable_sk_sand_...
NEXT_PUBLIC_SABLEPAY_MERCHANT_ID=00000000-0000-0000-0000-000000000000

// app/layout.tsx
import { SablePay } from '@sablepay/react-sablepay-js';

// Initialize outside component (runs once)
if (!SablePay.isInitialized()) {
  SablePay.initialize({
    apiKey: process.env.NEXT_PUBLIC_SABLEPAY_API_KEY!,
    merchantId: process.env.NEXT_PUBLIC_SABLEPAY_MERCHANT_ID!,
  });
}

export default function RootLayout({ children }) {
  return <html><body>{children}</body></html>;
}

// pages/_app.tsx
import { SablePay } from '@sablepay/react-sablepay-js';

if (!SablePay.isInitialized()) {
  SablePay.initialize({
    apiKey: process.env.NEXT_PUBLIC_SABLEPAY_API_KEY!,
    merchantId: process.env.NEXT_PUBLIC_SABLEPAY_MERCHANT_ID!,
  });
}

export default function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

// App.tsx
import { SablePay } from '@sablepay/react-native-sablepay-js';

SablePay.initialize({
  apiKey: 'sable_sk_sand_...',
  merchantId: '00000000-0000-0000-0000-000000000000',
  enableLogging: __DEV__,
});

import React, { useState } from 'react';
import { View, Button, Image } from 'react-native';
import { SablePay, QrCodeGenerator } from '@sablepay/react-native-sablepay-js';

export default function CheckoutScreen() {
  const [qrUrl, setQrUrl] = useState('');

  const pay = async () => {
    const sdk = SablePay.getInstance();
    const response = await sdk.createPayment({ amount: 10.50 });
    const qrGen = new QrCodeGenerator();
    const dataUrl = await qrGen.generatePaymentQr(response);
    setQrUrl(dataUrl || '');
  };

  return (
    <View>
      <Button title="Pay $10.50" onPress={pay} />
      {qrUrl ? <Image source={{ uri: qrUrl }} style={{ width: 300, height: 300 }} /> : null}
    </View>
  );
}

import React, { useEffect } from 'react';
import { View, Button, Image, Text } from 'react-native';
import { usePaymentFlow } from '@sablepay/react-native-sablepay-js';

export default function PaymentScreen() {
  const { state, qrDataUrl, error, startPayment, cancel, release } = usePaymentFlow();

  useEffect(() => {
    return () => release();
  }, [release]);

  return (
    <View>
      {state.type === 'idle' && <Button title="Pay $10.50" onPress={() => startPayment(10.50)} />}
      {state.type === 'creating' && <Text>Creating payment...</Text>}
      {state.type === 'awaiting' && qrDataUrl && (
        <>
          <Image source={{ uri: qrDataUrl }} style={{ width: 300, height: 300 }} />
          <Text>Scan the QR code with your wallet</Text>
          <Button title="Cancel" onPress={cancel} />
        </>
      )}
      {state.type === 'processing' && <Text>Processing payment...</Text>}
      {state.type === 'completed' && <Text>Payment complete!</Text>}
      {state.type === 'failed' && <Text>Error: {error}</Text>}
    </View>
  );
}

import React from 'react';
import { View, Button, Text } from 'react-native';
import { useSablePay } from '@sablepay/react-native-sablepay-js';

function PaymentComponent() {
  const { createPayment, getPaymentStatus, getEnvironment } = useSablePay();

  const handlePay = async () => {
    const response = await createPayment({ amount: 25.00 });
    const status = await getPaymentStatus(response.paymentId);
    console.log('Status:', status.status);
  };

  return (
    <View>
      <Text>Environment: {getEnvironment()}</Text>
      <Button title="Pay $25.00" onPress={handlePay} />
    </View>
  );
}

// Initialize (call once)
SablePay.initialize({
  apiKey: 'sable_sk_sand_...',     // Required
  merchantId: 'uuid-here',         // Required
  baseUrl: '...',                   // Optional (auto-detected)
  enableLogging: true,              // Optional (default: false)
});

// Get instance
const sdk = SablePay.getInstance();

// Create a payment
const response = await sdk.createPayment({
  amount: 10.50,
  metadata: { orderId: 'ORD-123' },
});
// response.paymentId, response.paymentLink, response.status, etc.

// Get payment status
const status = await sdk.getPaymentStatus('payment-id');
// status.status, status.transactionId, status.paidToken, etc.

// List payments
const payments = await sdk.listPayments(20, 0);

// Check environment
sdk.getEnvironment(); // 'sandbox' | 'production'

// Check if configured
sdk.isConfigured(); // boolean

// Create a payment flow
const flow = SablePay.createPaymentFlow();

// Release resources
SablePay.release();

const {
  state,           // PaymentFlowState
  startPayment,    // (amount, metadata?, callbacks?, options?) => Promise<void>
  cancel,          // () => void
  release,         // () => void
  isActive,        // boolean
  qrDataUrl,       // string | null
  paymentResponse, // CreatePaymentResponse | null
  paymentStatus,   // PaymentStatusResponse | null
  error,           // string | null
} = usePaymentFlow({
  onPaymentCreated: (response, qrUrl) => {},
  onStatusUpdate: (status) => {},
  onPaymentCompleted: (status) => {},
  onPaymentFailed: (error) => {},
  onStateChange: (state) => {},
});

const {
  sdk,              // SablePay instance
  createPayment,    // (request) => Promise<CreatePaymentResponse>
  getPaymentStatus, // (id) => Promise<PaymentStatusResponse>
  listPayments,     // (limit?, offset?) => Promise<PaymentStatusResponse[]>
  getEnvironment,   // () => 'sandbox' | 'production' | null
  isConfigured,     // () => boolean
  createPaymentFlow // (options?) => PaymentFlow
} = useSablePay();

interface CreatePaymentRequest {
  amount: number;                         // USD amount (0.01 - 1,000,000)
  items?: PaymentItem[];                  // Optional line items
  metadata?: Record<string, string>;      // Optional metadata
}

interface CreatePaymentResponse {
  paymentId: string;
  status: string;
  amount: number;
  acceptedTokens: string;
  paymentLink: string | null;
  businessName: string;
  expiresAt: string | null;
  createdAt: string;
}

interface PaymentStatusResponse {
  paymentId: string;
  amount: number;
  status: string;           // PENDING | COMPLETED | FAILED | EXPIRED
  transactionId?: string | null;
  paidToken?: string | null;
  paidNetwork?: string | null;
  paidAmount?: number | null;
  metadata?: Record<string, unknown> | null;
  createdAt: string;
  completedAt?: string | null;
  expiresAt?: string | null;
}

import { ApiException } from '@sablepay/react-native-sablepay-js';

try {
  await sdk.createPayment({ amount: 10.50 });
} catch (error) {
  if (error instanceof ApiException) {
    console.log(error.statusCode);    // 400, 401, 429, 500, etc.
    console.log(error.message);       // Error message
    console.log(error.requestId);     // For debugging
    console.log(error.isRetryable);   // true for 5xx and 429
    console.log(error.isAuthError);   // true for 401
    console.log(error.retryAfter);    // Seconds to wait (for 429)
  }
}

import { QrCodeGenerator } from '@sablepay/react-native-sablepay-js';

const generator = new QrCodeGenerator({ width: 400, height: 400 });

// From payment response
const dataUrl = await generator.generatePaymentQr(response);

// From any text
const qr = await generator.generate('https://example.com');

// As SVG
const svg = await generator.generateSvg('https://example.com');

import { PaymentPoller } from '@sablepay/react-native-sablepay-js';

const poller = new PaymentPoller((id) => sdk.getPaymentStatus(id));

// Callback-based
poller.startPolling('payment-id', (result) => {
  if (result.success) console.log(result.data.status);
});
poller.stopPolling();

// Promise-based (awaits terminal state)
const finalStatus = await poller.pollUntilTerminal('payment-id');

// src/config/environment.ts
export const environment = {
  production: false,
  sablepayApiKey: 'sable_sk_sand_...',
  sablepayMerchantId: '00000000-0000-0000-0000-000000000000',
  sablepayBaseUrl: 'https://sandbox-api.sablepay.io/api/v1/',
};

import React, { useEffect, useState } from 'react';
import { View, Text } from 'react-native';
import { SablePay } from '@sablepay/react-native-sablepay-js';

export default function App() {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    SablePay.initialize({
      apiKey: 'sable_sk_sand_...',
      merchantId: '00000000-0000-0000-0000-000000000000',
      enableLogging: __DEV__,
    });

    setReady(true);

    return () => SablePay.release();
  }, []);

  if (!ready) return <Text>Loading...</Text>;

  return <View>{/* Your payment screens */}</View>;
}