Data Models

This section describes the structure of objects used throughout the API. Understanding these models is crucial for successful API integration.

Core Models

Merchant

Represents a business account on the platform.

interface Merchant {
  merchant_id: string;      // UUID
  name: string;            // Business name
  email: string;           // Contact email
  phone_number: string;    // Contact phone
  onboarded: boolean;      // Onboarding status
  country: string;         // Country code
  avatar_url?: string;     // Profile image
  preferred_language?: string;
  timezone?: string;
  metadata?: Record<string, any>;
  created_at: string;      // ISO datetime
  updated_at: string;      // ISO datetime
}

Product

Represents an item or service that can be purchased.

interface Product {
  product_id: string;      // UUID
  merchant_id: string;     // UUID
  name: string;
  description?: string;
  price: number;
  currency_code: CurrencyCode;
  image_url?: string;
  is_active: boolean;
  display_on_storefront: boolean;
  created_at: string;      // ISO datetime
  updated_at: string;      // ISO datetime
}

Transaction

Represents a payment transaction.

interface Transaction {
  transaction_id: string;  // UUID
  merchant_id: string;     // UUID
  customer_id: string;     // UUID
  amount: number;
  currency_code: CurrencyCode;
  status: TransactionStatus;
  provider_code: ProviderCode;
  payment_method_code: PaymentMethodCode;
  reference_id: string;
  metadata?: Record<string, any>;
  created_at: string;      // ISO datetime
  updated_at: string;      // ISO datetime
}

Subscription Models

SubscriptionPlan

Defines a recurring billing plan.

interface SubscriptionPlan {
  plan_id: string;         // UUID
  merchant_id: string;     // UUID
  name: string;
  description?: string;
  amount: number;
  currency_code: CurrencyCode;
  billing_frequency: BillingFrequency;
  failed_payment_action: FailedPaymentAction;
  charge_day?: number;
  metadata?: Record<string, any>;
  created_at: string;      // ISO datetime
  updated_at: string;      // ISO datetime
}

Payment Models

PaymentLink

Represents a shareable payment URL.

interface PaymentLink {
  link_id: string;         // UUID
  merchant_id: string;     // UUID
  title: string;
  public_description?: string;
  private_description?: string;
  amount?: number;
  currency_code: CurrencyCode;
  allowed_providers: ProviderCode[];
  url: string;
  expires_at?: string;     // ISO datetime
  created_at: string;      // ISO datetime
  updated_at: string;      // ISO datetime
}

CheckoutSession

Represents a payment collection session.

interface CheckoutSession {
  checkout_session_id: string;
  merchant_id: string;     // UUID
  url: string;
  status: "open" | "completed" | "expired";
  success_url: string;
  cancel_url: string;
  provider_codes: ProviderCode[];
  expires_at: string;      // ISO datetime
  created_at: string;      // ISO datetime
}

Enums

CurrencyCode

Supported currency codes.

enum CurrencyCode {
  XOF = "XOF",  // West African CFA franc
  USD = "USD",  // US Dollar
  EUR = "EUR"   // Euro
}

ProviderCode

Available payment providers.

enum ProviderCode {
  ORANGE = "ORANGE",
  WAVE = "WAVE",
  ECOBANK = "ECOBANK",
  MTN = "MTN",
  MOOV = "MOOV",
  AIRTEL = "AIRTEL",
  MPESA = "MPESA",
  // ... other providers
}

PaymentMethodCode

Supported payment methods.

enum PaymentMethodCode {
  MOBILE_MONEY = "MOBILE_MONEY",
  CARDS = "CARDS",
  BANK_TRANSFER = "BANK_TRANSFER",
  USSD = "USSD",
  QR_CODE = "QR_CODE",
  E_WALLET = "E_WALLET",
  CRYPTO = "CRYPTO"
}

TransactionStatus

Possible transaction states.

enum TransactionStatus {
  PENDING = "pending",
  COMPLETED = "completed",
  FAILED = "failed",
  REFUNDED = "refunded"
}

BillingFrequency

Subscription billing intervals.

enum BillingFrequency {
  WEEKLY = "weekly",
  BIWEEKLY = "bi-weekly",
  MONTHLY = "monthly",
  QUARTERLY = "quarterly",
  SEMIANNUAL = "semi-annual",
  YEARLY = "yearly",
  ONETIME = "one-time"
}

Webhook Models

WebhookEvent

Represents an event notification.

interface WebhookEvent {
  event_type: WebhookEventType;
  merchant_id: string;
  data: Record<string, any>;
  created_at: string;
}

WebhookEventType

Types of events that trigger webhooks.

enum WebhookEventType {
  TRANSACTION_CREATED = "TRANSACTION_CREATED",
  TRANSACTION_COMPLETED = "TRANSACTION_COMPLETED",
  TRANSACTION_FAILED = "TRANSACTION_FAILED",
  REFUND_COMPLETED = "REFUND_COMPLETED",
  // ... other event types
}

API Endpoints Error Handling