Use plans and subscriptions for recurring billing. Kyshi supports card auto-collection and invoice-based collection for non-card methods such as bank_transfer, bank, and mobile_money.

Create A Plan

const plan = await kyshi.plans.create({
  name: 'Gold',
  description: 'Gold monthly plan',
  interval: 'monthly',
  amount: 1000,
  localCurrency: 'NGN',
  hostedPage: true,
});

Create A Subscription

const subscription = await kyshi.subscriptions.create({
  planCode: plan.code!,
  customer: '[email protected]',
  paymentMethod: 'card',
  redirectUrl: 'https://merchant.example.com/subscriptions/callback',
});

For non-card collection, create the subscription with a non-card paymentMethod:

const manualSubscription = await kyshi.subscriptions.create({
  planCode: plan.code!,
  customer: '[email protected]',
  paymentMethod: 'bank_transfer',
  redirectUrl: 'https://merchant.example.com/subscriptions/callback',
});

card subscriptions can charge a saved card or authorization automatically. bank_transfer, bank, and mobile_money subscriptions generate invoices and payment links or instructions for the customer to complete payment. Use plans with sendInvoices: true when customers should receive invoice and payment reminders.

Manage A Subscription

await kyshi.subscriptions.manage(subscription.id!, {
  action: 'cancel_at_period_end',
});

await kyshi.subscriptions.updateStatus(subscription.id!, {
  action: 'activate',
});

Retry Or Update Payment

const retry = await kyshi.subscriptions.retryPayment(subscription.id!, {
  force: true,
});

const updateCard = await kyshi.subscriptions.updateCard(subscription.id!, {
  redirectUrl: 'https://merchant.example.com/update-card',
});

Invoices And Attempts

const invoices = await kyshi.subscriptions.listInvoices(subscription.id!);
const attempts = await kyshi.subscriptions.listPaymentAttempts(subscription.id!);

Rates

Use rates when your integration needs configured MOR rate and fee information.

const rateAndFee = await kyshi.rates.get({
  currency: 'NGN',
  rateType: 'MOR_RATES',
});

const customRateAndFee = await kyshi.customRates.get({
  currency: 'GHS',
});

Methods

Resource	Methods
`kyshi.plans`	`create`, `list`, `retrieve`
`kyshi.subscriptions`	`create`, `list`, `retrieve`, `manage`, `updateStatus`, `updateCard`, `retryPayment`, `charge`, `listInvoices`, `retrieveInvoice`, `listPaymentAttempts`, `listInvoicePaymentAttempts`
`kyshi.rates`	`get`
`kyshi.customRates`	`get`

For exact API fields and response schemas, see Reference > Plans, Reference > Subscriptions, and Reference > Rates.