Provider-Specific Options

Sanwo’s unified API covers the options that every provider shares: amount, currency, customer, reference, channels, and metadata. But each provider also has features unique to it – subscription plans, split payments, checkout customizations, and more.

You can access these through provider-specific options without losing portability. If you later switch providers, these options are silently ignored rather than causing errors.

How to pass provider options

The mechanism differs slightly by platform.

Web, React, and React Native

Use the sanwoProviderOptions field inside your checkout options. It accepts any key-value pairs, which are forwarded directly to the underlying provider SDK.

const result = await sanwo({
  amount: 500000,
  currency: "NGN",
  customer: { email: "customer@example.com" },
  sanwoProviderOptions: {
    // These are passed through to the provider SDK as-is
    channels: ["card", "bank_transfer"],
  },
});

Flutter

Some common provider options like channels are available as typed fields on CheckoutOptions. For everything else, use the extra map:

final result = await sanwo(
  context: context,
  options: CheckoutOptions(
    amount: 500000,
    currency: 'NGN',
    customer: CheckoutCustomer(email: 'customer@example.com'),
    channels: ['card', 'bank_transfer'],
    extra: {'subaccount': 'ACCT_xxxxxxxxxxxx'},
  ),
);

iOS and Android

On native mobile SDKs, provider-specific fields like channels, extra, and method are available as flat properties on CheckoutOptions. The exact fields vary by platform – see the iOS and Android SDK docs.

Paystack

Restrict payment channels

Limit which payment methods appear in the checkout:

const result = await sanwo({
  amount: 500000,
  currency: "NGN",
  customer: { email: "customer@example.com" },
  sanwoProviderOptions: {
    channels: ["card", "bank_transfer"],
  },
});

Available channels: card, bank, ussd, qr, mobile_money, bank_transfer, eft.

Subscription plans

Charge a customer on a recurring Paystack plan:

const result = await sanwo({
  amount: 500000,
  currency: "NGN",
  customer: { email: "customer@example.com" },
  sanwoProviderOptions: {
    plan: "PLN_xxxxxxxxxxxx",
    quantity: 1,
  },
});

Split payments

Route part of the payment to a subaccount:

const result = await sanwo({
  amount: 500000,
  currency: "NGN",
  customer: { email: "customer@example.com" },
  sanwoProviderOptions: {
    subaccount: "ACCT_xxxxxxxxxxxx",
  },
});

You can also use splitCode for pre-configured split groups or an inline split object for dynamic splits. See the Paystack provider page for full details.

Flutterwave

Checkout customizations

Brand the Flutterwave checkout modal with your store name and logo:

const result = await sanwo({
  amount: 250000,
  currency: "NGN",
  customer: { email: "customer@example.com" },
  sanwoProviderOptions: {
    customizations: {
      title: "My Store",
      description: "Order #1234",
      logo: "https://mystore.com/logo.png",
    },
  },
});

Payment plans

Set up recurring billing with a Flutterwave payment plan:

const result = await sanwo({
  amount: 100000,
  currency: "NGN",
  customer: { email: "customer@example.com" },
  sanwoProviderOptions: {
    paymentPlan: 123,
  },
});

See the Flutterwave provider page for split payment configuration and additional options.

Razorpay

Order ID

Razorpay recommends creating an order on your server and passing the orderId to prevent amount tampering:

const result = await sanwo({
  amount: 50000,
  currency: "INR",
  customer: { email: "customer@example.com" },
  sanwoProviderOptions: {
    orderId: "order_xxxxxxxxxxxx",
  },
});

Theme

Customize the Razorpay checkout colors:

const result = await sanwo({
  amount: 50000,
  currency: "INR",
  customer: { email: "customer@example.com" },
  sanwoProviderOptions: {
    orderId: "order_xxxxxxxxxxxx",
    theme: {
      color: "#4f46e5",
    },
  },
});

See the Razorpay provider page for notes, image, and other options.

Monnify

Contract code (required)

Monnify requires a contractCode for every transaction. This identifies your merchant contract:

const result = await sanwo({
  amount: 500000,
  currency: "NGN",
  customer: { email: "customer@example.com" },
  sanwoProviderOptions: {
    contractCode: "1234567890",
  },
});

Caution

The contractCode is required for Monnify. Checkouts will fail without it.

Interswitch

Pay item ID (required)

Interswitch requires a payItemId to identify the payment item:

const result = await sanwo({
  amount: 500000,
  currency: "NGN",
  customer: { email: "customer@example.com" },
  sanwoProviderOptions: {
    payItemId: "Default_Payable_MX_xxxxxxxxxxxx",
  },
});

Caution

The payItemId is required for Interswitch. Checkouts will fail without it.

Cross-platform examples

Here is a Paystack channels example on every platform:

Web / React

const result = await sanwo({
  amount: 500000,
  currency: "NGN",
  customer: { email: "customer@example.com" },
  sanwoProviderOptions: {
    channels: ["card", "bank_transfer"],
  },
});

React Native

const { checkout } = useSanwoCheckout();

const result = await checkout({
  amount: 500000,
  currency: "NGN",
  customer: { email: "customer@example.com" },
  sanwoProviderOptions: {
    channels: ["card", "bank_transfer"],
  },
});

Flutter

final result = await sanwo(
  context: context,
  options: CheckoutOptions(
    amount: 500000,
    currency: 'NGN',
    customer: CheckoutCustomer(email: 'customer@example.com'),
    channels: ['card', 'bank_transfer'],
  ),
);

Kotlin

val options = CheckoutOptions(
    amount = 500000,
    currency = "NGN",
    customer = CheckoutCustomer(email = "customer@example.com"),
    channels = listOf("card", "bank_transfer"),
    extra = mapOf("subaccount" to "ACCT_xxxxxxxxxxxx")
)
sanwo.launchCheckout(this, launcher, options)

What happens when you switch providers

Provider-specific options are silently ignored when using a different provider. There are no errors and no crashes – the options simply have no effect.

const result = await sanwo({
  amount: 500000,
  currency: "NGN",
  customer: { email: "customer@example.com" },
  sanwoProviderOptions: {
    // Paystack-specific: ignored if using Flutterwave
    plan: "PLN_xxxxxxxxxxxx",
    // Flutterwave-specific: ignored if using Paystack
    customizations: { title: "My Store" },
  },
});

This means you can safely include options for multiple providers in the same object if needed. Only the options relevant to the active provider take effect.

For a complete reference of each provider’s options, see the individual provider pages:

• Paystack
• Flutterwave
• Razorpay