API Reference

interface Customer {
  /** The unique identifier of the customer. */
  id: string;

  /** The email address of the customer. */
  email: string;

  /** The full name of the customer. */
  name: string;

  /** The phone number of the customer. . */
  phone: string | null;

  /** Arbitrary key-value metadata attached to the customer. */
  metadata?: Record<string, string>;

  /** Provider-specific or custom fields not covered by the unified model. */
  custom_fields?: Record<string, unknown>;

  /** When the customer was created. */
  created_at: Date;

  /** When the customer was last updated.  */
  updated_at: Date | null;
}

const customer = await paykit.customers.create({
  email: 'user@example.com',
  name: 'Jane Doe',
  phone: '+1234567890',
  metadata: { plan: 'pro' },
});

const customer = await paykit.customers.retrieve('cus_123');

const customer = await paykit.customers.update('cus_123', {
  name: 'Jane Smith',
});

interface Checkout {
  /** The unique identifier of the checkout session. */
  id: string;

  /** The customer linked to this resource. */
  customer: Payee | null;

  /** The URL to redirect the customer to for payment. */
  payment_url: string;

  /** Arbitrary key-value metadata attached to the session. */
  metadata: Record<string, string> | null;

  /** Whether this is a one-time payment or recurring subscription. */
  session_type: 'one_time' | 'recurring';

  /** The products included in this checkout. */
  products: Array<{ id: string; quantity: number }>;

  /** ISO 4217 currency code (e.g. USD, NGN). */
  currency: string;

  /** Total amount in the smallest currency unit (e.g. cents, kobo). */
  amount: number;

  /** Subscription billing details, if session_type is recurring. */
  subscription?: CheckoutSubscription | null;
}

const checkout = await paykit.checkouts.create({
  customer: 'cus_123',           // or { email: 'user@example.com' }
  item_id: 'price_123',
  session_type: 'one_time',
  quantity: 1,
  metadata: { source: 'web' },
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  provider_metadata: { /* typed per provider */ },
});

const checkout = await paykit.checkouts.retrieve('cs_123');

type SubscriptionBillingInterval =
  | 'day' | 'week' | 'month' | 'year'
  | { type: 'custom'; durationMs: number };

interface Subscription {
  /** The unique identifier of the subscription. */
  id: string;

  /** The customer linked to this resource. */
  customer: Payee | null;

  /** Recurring amount in the smallest currency unit. */
  amount: number;

  /** ISO 4217 currency code. */
  currency: string;

  /** Current lifecycle status of the subscription. */
  status: 'active' | 'past_due' | 'canceled' | 'expired' | 'trialing' | 'pending';

  /** Start of the current billing period. */
  current_period_start: Date;

  /** End of the current billing period (next renewal date). */
  current_period_end: Date;

  /** The provider item or plan ID this subscription is tied to. */
  item_id: string;

  /** How often the subscription renews. Custom intervals use durationMs. */
  billing_interval: SubscriptionBillingInterval;

  /** Arbitrary key-value metadata. */
  metadata: Record<string, string> | null;

  /** Provider-specific or custom fields. */
  custom_fields: Record<string, unknown> | null;

  /** Whether the subscription requires user action (e.g. 3DS). */
  requires_action: boolean;

  /** Redirect URL if action is required. */
  payment_url: string | null;
}

const subscription = await paykit.subscriptions.create({
  customer: 'cus_123',
  item_id: 'price_123',
  metadata: { plan: 'pro' },
});

const subscription = await paykit.subscriptions.retrieve('sub_123');

const subscription = await paykit.subscriptions.cancel('sub_123');

interface Payment {
  /** The unique identifier of the payment (reference). */
  id: string;

  /** Amount in the smallest currency unit (e.g. cents, kobo). */
  amount: number;

  /** ISO 4217 currency code. */
  currency: string;

  /** The customer linked to this resource. */
  customer: Payee | null;

  /**
   * Current status of the payment.
   * - pending: created but not yet processed
   * - processing: being processed by the provider
   * - requires_action: needs user action (3DS, bank verification, etc.)
   * - requires_capture: authorized but not yet captured
   * - succeeded: payment completed successfully
   * - canceled: payment was canceled
   * - failed: payment failed
   */
  status:
    | 'pending'
    | 'processing'
    | 'requires_action'
    | 'requires_capture'
    | 'succeeded'
    | 'canceled'
    | 'failed';

  /** Arbitrary key-value metadata attached to the payment. */
  metadata: Record<string, string>;

  /** The provider item ID linked to this payment. */
  item_id: string | null;

  /** Whether the payment is waiting for user action before it can proceed. */
  requires_action: boolean;

  /** URL to redirect the user to if requires_action is true. */
  payment_url: string | null;
}

const payment = await paykit.payments.retrieve('pay_123');

interface Refund {
  /** The unique identifier of the refund. */
  id: string;

  /** Amount refunded in the smallest currency unit. */
  amount: number;

  /** ISO 4217 currency code. */
  currency: string;

  /** Human-readable reason for the refund */
  reason: string | null;

  /** Arbitrary key-value metadata attached to the refund. */
  metadata: Record<string, string> | null;
}

const refund = await paykit.refunds.create({
  payment_id: 'pay_123',
  amount: 1000,
  reason: 'requested_by_customer',
  provider_metadata: {
    /* typed per provider */
  },
});

interface Invoice {
  /** The unique identifier of the invoice. */
  id: string;

  /** The customer linked to this resource. */
  customer: Payee | null;

  /** The subscription this invoice belongs to. */
  subscription_id: string | null;

  /** Whether this invoice is for a one-time payment or a recurring subscription. */
  billing_mode: 'one_time' | 'recurring';

  /** Amount paid in the smallest currency unit (e.g. cents). */
  amount_paid: number;

  /** ISO 4217 currency code (e.g. USD, EUR). */
  currency: string;

  /** Current status of the invoice. */
  status: 'paid' | 'open';

  /** ISO 8601 timestamp of when the invoice was paid. */
  paid_at: string | null;

  /** Individual line items on the invoice. */
  line_items: Array<{ id: string; quantity: number }> | null;

  /** Arbitrary key-value metadata. */
  metadata: Record<string, string> | null;

  /** Provider-specific or custom fields. */
  custom_fields: Record<string, unknown> | null;
}

type Payee = { email: string } | { id: string | number };

// Both are valid when creating resources
await paykit.checkouts.create({ customer: { email: 'user@example.com' }, ... });
await paykit.checkouts.create({ customer: { id: 'cus_123' }, ... });