Quick Start

Pick your platform, install two packages (Sanwo core + a provider), and start accepting payments.

Installation & first checkout

Web / JS

npm i @sanwohq/web @sanwohq/paystack

import { createSanwo } from "@sanwohq/web";
import { paystack } from "@sanwohq/paystack";

const sanwo = createSanwo(paystack({ publicKey: "pk_test_xxx" }));

const result = await sanwo({
  amount: 500000, // 5,000.00 NGN in kobo
  currency: "NGN",
  customer: { email: "customer@example.com" },
});

if (result.status === "successful") {
  console.log("Payment ref:", result.reference);
}

React

npm i @sanwohq/react @sanwohq/paystack

import { SanwoReactProvider, useSanwoCheckout } from "@sanwohq/react";
import { paystack } from "@sanwohq/paystack";

// Wrap your app
function App() {
  return (
    <SanwoReactProvider provider={paystack({ publicKey: "pk_test_xxx" })}>
      <Checkout />
    </SanwoReactProvider>
  );
}

function Checkout() {
  const checkout = useSanwoCheckout();

  const pay = async () => {
    const result = await checkout({
      amount: 500000,
      currency: "NGN",
      customer: { email: "customer@example.com" },
    });

    if (result.status === "successful") {
      console.log("Payment ref:", result.reference);
    }
  };

  return <button onClick={pay}>Pay NGN 5,000</button>;
}

React Native

npm i @sanwohq/react-native @sanwohq/paystack

import { SanwoProvider, useSanwoCheckout } from "@sanwohq/react-native";
import { paystack } from "@sanwohq/paystack";

function App() {
  return (
    <SanwoProvider provider={paystack({ publicKey: "pk_test_xxx" })}>
      <Checkout />
    </SanwoProvider>
  );
}

function Checkout() {
  const checkout = useSanwoCheckout();

  const pay = async () => {
    const result = await checkout({
      amount: 500000,
      currency: "NGN",
      customer: { email: "customer@example.com" },
    });

    if (result.status === "successful") {
      alert(`Paid! Ref: ${result.reference}`);
    }
  };

  return <Button title="Pay NGN 5,000" onPress={pay} />;
}

Flutter

flutter pub add sanwo_flutter sanwo_paystack

import 'package:sanwo_flutter/sanwo_flutter.dart';
import 'package:sanwo_paystack/sanwo_paystack.dart';

final sanwo = Sanwo(
  provider: Paystack(publicKey: 'pk_test_xxx'),
);

final result = await sanwo.checkout(
  CheckoutOptions(
    amount: 500000, // 5,000.00 NGN in kobo
    currency: 'NGN',
    customer: Customer(email: 'customer@example.com'),
  ),
);

if (result.status == CheckoutStatus.successful) {
  print('Payment ref: ${result.reference}');
}

iOS / Swift

Add the Swift package from https://github.com/Sanwohq/ios in Xcode (File > Add Package Dependencies).

import Sanwo
import SanwoPaystack

let sanwo = Sanwo(provider: Paystack(publicKey: "pk_test_xxx"))

let result = try await sanwo.checkout(
    amount: 500000, // 5,000.00 NGN in kobo
    currency: "NGN",
    customer: Customer(email: "customer@example.com")
)

switch result.status {
case .successful:
    print("Payment ref: \(result.reference)")
case .cancelled:
    print("User cancelled")
case .failed(let error):
    print("Failed: \(error)")
case .pending:
    print("Pending: \(result.reference)")
}

Android / Kotlin

Add JitPack to your settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        maven { url = uri("https://jitpack.io") }
    }
}

Add the dependency:

implementation("com.github.Sanwohq.android:sanwo:1.0.0")

import com.sanwohq.android.Sanwo
import com.sanwohq.android.paystack.Paystack

val sanwo = Sanwo(provider = Paystack(publicKey = "pk_test_xxx"))

val result = sanwo.checkout(
    amount = 500000, // 5,000.00 NGN in kobo
    currency = "NGN",
    customer = Customer(email = "customer@example.com")
)

when (result.status) {
    Status.SUCCESSFUL -> println("Payment ref: ${result.reference}")
    Status.CANCELLED -> println("User cancelled")
    Status.FAILED -> println("Failed: ${result.error}")
    Status.PENDING -> println("Pending: ${result.reference}")
}

CheckoutOptions

All platforms share the same checkout options:

Field	Type	Required	Description
amount	number	Yes	Amount in minor units (kobo, cents, paise). 500000 = 5,000.00 NGN.
currency	string	Yes	ISO 4217 currency code ("NGN", "USD", "INR", etc.).
customer	{ email: string }	Yes	Customer info. email is always required.
reference	string	No	Your own transaction reference. Sanwo generates one if omitted.
metadata	Record<string, unknown>	No	Arbitrary key-value data passed through to the provider.
description	string	No	Human-readable description of the charge.
sanwoProviderOptions	object	No	Provider-specific overrides. Escape hatch for options Sanwo doesn’t abstract.

CheckoutResult

The result is a discriminated union on status:

// Payment succeeded
{ status: "successful", reference: string, providerResponse: unknown }

// User closed the checkout
{ status: "cancelled" }

// Something went wrong
{ status: "failed", error: string }

// Payment initiated but not yet confirmed (e.g. bank transfer)
{ status: "pending", reference: string }

Always check result.status before accessing other fields.

Next steps

• Choose a provider to see supported regions, currencies, and payment methods.
• Explore your platform’s SDK guide under SDKs in the sidebar for advanced usage.