Types

Every enum and object type the API endpoints refer to, in one place.

Currencies and channels

enum CurrencyType {
  FIAT = 'fiat',
  CRYPTO = 'crypto',
  MERCHANT_BALANCE = 'merchant_balance',
}

enum PaymentChannel {
  BANK = 'bank',
  AIRTIME = 'airtime',
  MOBILE_MONEY = 'mobile_money',
  PAYBILL = 'paybill',           // Kenya, payout only
  BUY_GOODS = 'buy_goods',       // Kenya, payout only
  DIGITAL_WALLET = 'digital_wallet',
  MERCHANT_BALANCE = 'merchant_balance',
  CRYPTO = 'crypto',
}

type OrderCurrencyDetails =
  | OrderCryptoDetails
  | OrderFiatDetails
  | OrderMerchantDetails;

type OrderCryptoDetails = {
  network: string;
  asset: string;
  contractAddress?: string; // omitted on a native asset, never null
};

type OrderFiatDetails = {
  countryIsoCode: string;
  carrier?: { code: string; name: string; _id: string }; // the carrier chosen for this order
}

type OrderMerchantDetails = { merchantName: string }

contractAddress is omitted, not null, on a native asset — test for absence rather than comparing against null. Note also that OrderFiatDetails carries the single carrier chosen for the order; the carriers array of everything a channel supports is a different shape, returned by Get available currencies.

Orders

enum OrderStatus {
  DEPOSIT_AWAITING = 'deposit_awaiting',     // waiting for the user to pay
  DEPOSIT_VALIDATING = 'deposit_validating', // payment reported, being checked
  DEPOSIT_SUCCESSFUL = 'deposit_successful', // deposit checked out
  DEPOSIT_INVALID = 'deposit_invalid',       // wrong amount, narration or account
  DEPOSIT_CANCELED = 'deposit_canceled',     // cancelled before payment
  DEPOSIT_EXPIRED = 'deposit_expired',       // not paid in time
  PAYOUT_PENDING = 'payout_pending',         // sending the funds out
  PAYOUT_SUCCESSFUL = 'payout_successful',   // delivered
  PAYOUT_FAILED = 'payout_failed',           // delivery failed; retried via payout_pending
  REFUND_INITIATED = 'refund_initiated',     // refund decided, not started
  REFUND_PENDING = 'refund_pending',
  REFUND_SUCCESSFUL = 'refund_successful',
  REFUND_FAILED = 'refund_failed',           // retried via refund_initiated
}

enum OrderType {
  ON_RAMP = 'on_ramp',
  OFF_RAMP = 'off_ramp',
  SETTLEMENT = 'settlement',                             // merchant balance <-> fiat or crypto
  MERCHANT_BALANCE_DEPOSIT = 'merchant_balance_deposit', // you topping up your own balance
  MERCHANT_BALANCE_WITHDRAWAL = 'merchant_balance_withdrawal',
}

enum FlowType {
  REGULAR = 'regular',
  MERCHANT_BALANCE_CRYPTO = 'merchant_balance_crypto', // your own balance, via crypto
}

enum Source {
  WIDGET = 'widget', // created in the Pay Widget
  API = 'api',       // created through the Merchant API
}

enum OperationType {
  DEPOSIT = 'deposit',
  PAYOUT = 'payout',
  REFUND = 'refund',
}

type OrderStatusChangeLog = {
  oldStatus?: OrderStatus; // absent on a deposit_canceled entry
  newStatus: OrderStatus;
  date: Date;
};

Which transitions are real, and which statuses are actually final, is on Order statuses — fewer are final than the names suggest. The full Order object every order endpoint returns is spelled out on Get order.

Pricing

type Cashout = {
  exchangeRate: number;           // before fees
  exchangeRateAfterFees: number;  // amountBeforeFees / amountAfterFeesUsd, to 4 dp
  amountBeforeFees: number;
  amountAfterFees: number;
  amountBeforeFeesUsd: number;
  amountAfterFeesUsd: number;
  feeSettings: FeeSetting[];      // the rules that were applied
  chargedFees: ChargedFee[];      // what each rule cost, in the leg's currency
  chargedFeesUsd: ChargedFee[];   // ...and in USD
  totalChargedFees: number;
  totalChargedFeesUsd: number;
  chargedFeesPerRecipient: Partial<Record<FeeRecipient, number>>;
  chargedFeesPerRecipientUsd: Partial<Record<FeeRecipient, number>>;
};

type FeeSetting =
  | {
  id: string;
  recipient: FeeRecipient;
  type: FeeType.FLAT_AMOUNT;
  value: number;
  min: number;
  max: number | 'Infinity'
}
  | {
  id: string;
  recipient: FeeRecipient;
  type: FeeType.PERCENTAGE;
  value: number;      // percent
  min: number;        // amount range this rule applies to
  max: number | 'Infinity';
  minCap?: number;    // floor on the fee itself
  maxCap?: number     // ceiling on the fee itself
};

type ChargedFee = { id: string; type: FeeType; recipient: FeeRecipient; amount: number };

enum FeeRecipient { MERCHANT = 'merchant', PROVIDER = 'provider', PLATFORM = 'platform', BLOCKCHAIN = 'blockchain' }

enum FeeType { PERCENTAGE = 'percentage', FLAT_AMOUNT = 'flat_amount' }

chargedFees with recipient: "merchant" is your revenue on the order. recipient: "blockchain" is gas, and recipient: "provider" is the liquidity provider's cut. The platform's own fee has the id service_fee.

Transfer instructions

enum TransferType {
  MANUAL = 'manual',
  REDIRECT = 'redirect',
  STK_PUSH = 'stk_push',
  OTP_STK_PUSH = 'otp_stk_push',
  USSD = 'ussd',
}

type TransferInstructions =
  | ManualTransferInstructions
  | RedirectTransferInstructions
  | StkPushTransferInstructions
  | OtpStkPushTransferInstructions
  | UssdTransferInstructions;

type ManualTransferInstructions = {
  type: TransferType.MANUAL;
  instructionsText: string;
  warningText?: string;
  transferDetails: TransferDetail[];
  fieldsToConfirmOrder: RequiredField[];
};

type RedirectTransferInstructions = {
  type: TransferType.REDIRECT;
  paymentUrl: string;
  redirectedToPaymentUrl: boolean;
  intermediateActionButtonText: string;
  instructionsText: string;
  warningText?: string;
  transferDetails: TransferDetail[];
  fieldsToConfirmOrder: RequiredField[];
};

type StkPushTransferInstructions = {
  type: TransferType.STK_PUSH;
  isIntermediateActionAvailable: boolean;
  intermediateActionExecuted: boolean;
  intermediateActionButtonText: string;
  intermediateActionMaxAttempts: number;
  intermediateActionAttempts: number;
  intermediateActionNextAttemptAvailableAt: Date;
  intermediateActionTimeoutMs: number;
  instructionsText: string;
  warningText?: string;
  transferDetails: TransferDetail[];
  fieldsToConfirmOrder: RequiredField[];
};

type OtpStkPushTransferInstructions = {
  type: TransferType.OTP_STK_PUSH;
  otpChannel: 'sms' | 'ussd' | 'email' | 'whatsapp';
  otpAssociativeId?: string;
  intermediateActionRequired: boolean;   // OTP only
  intermediateActionExecuted: boolean;
  isIntermediateActionAvailable: boolean;
  intermediateActionButtonText: string;
  intermediateActionMaxAttempts: number;
  intermediateActionAttempts: number;
  intermediateActionNextAttemptAvailableAt: Date;
  intermediateActionTimeoutMs: number;
  fieldsForIntermediateAction: RequiredField[];
  instructionsText: string;
  warningText?: string;
  transferDetails: TransferDetail[];
  fieldsToConfirmOrder: RequiredField[];
};

type UssdTransferInstructions = {
  type: TransferType.USSD;
  ussdCode: string;
  instructionsText: string;
  warningText?: string;
  transferDetails: TransferDetail[];
  fieldsToConfirmOrder?: RequiredField[];
};

type TransferDetail = { id: TransferDetailId; label: string; description?: string; value?: string };

enum TransferDetailId {
  RECIPIENT_WALLET_ADDRESS = 'recipientWalletAddress',
  SENDER_WALLET_ADDRESS = 'senderWalletAddress',
  AMOUNT_TO_SEND = 'amountToSend',
  CRYPTO_TRANSACTION_REQUEST_ADDITIONAL_DATA = 'cryptoTransactionRequestAdditionalData',
  RECIPIENT_BANK_NAME = 'recipientBankName',
  RECIPIENT_BANK_ACCOUNT_NUMBER = 'recipientBankAccountNumber',
  RECIPIENT_BANK_ACCOUNT_NAME = 'recipientBankAccountName',
  RECIPIENT_BANK_BRANCH_CODE = 'bankBranchCode',
  RECIPIENT_BANK_BANK_SWIFT_CODE = 'bankSwiftCode',
  RECIPIENT_PHONE_NUMBER = 'recipientPhoneNumber',
  BANK_TRANSFER_NARRATION = 'bankTransferNarration',
}

otpChannel tells you how the code reached the user, so you can word your prompt correctly. Do not assume SMS. Render transferDetails as it arrives rather than picking known ids — the set grows.

What each transfer type means for your UI is on Transfer types explanation.

Fields

type RequiredField = {
  key: string;
  type: FieldType;
  label: string;
  required: boolean;
  options?: {
    value: string;
    label: string;
    iconUrl?: string;   // e.g. a bank logo
    featured?: boolean; // show this option first
  }[];
  defaultValue?: string;
};

enum FieldType {
  NUMBER = 'number',
  STRING = 'string',
  DATE = 'date',
  BOOLEAN = 'boolean',
  EMAIL = 'email',
  PHONE = 'phone',
  ENUM = 'enum',
}

// The same values echoed back on an order, labelled and typed for display.
type FormattedUserField = {
  key: string;
  label: string;
  value: string | number | boolean | Date;
  type: FieldType;
};

// Sandbox only. Set on fieldsToCreateOrder to force an outcome.
enum SandboxForcedFlow {
  DEPOSIT_SUCCESS = 'deposit_success',
  DEPOSIT_INVALID = 'deposit_invalid',
  DEPOSIT_UNDERPAYMENT = 'deposit_underpayment', // pays 50%
  DEPOSIT_OVERPAYMENT = 'deposit_overpayment',   // pays 200%
  PAYOUT_SUCCESS = 'payout_success',
  PAYOUT_FAILED = 'payout_failed',
}

For any field with type: "enum", the options array on that field is the authoritative list of accepted values — read it rather than hard-coding one. That applies to bankCode, carrierCode, and to the sandbox-only depositSandboxForcedFlow / payoutSandboxForcedFlow fields, which do not offer every member of the enum on every leg: a fiat deposit typically offers all four deposit_* values, a crypto deposit only deposit_success and deposit_invalid, and a payout leg only payout_success and payout_failed.

KYC

enum KycType { BASIC = 'basic', ADVANCED = 'advanced' }

// Treat this set as open-ended: historical records can carry values outside it,
// so branch on passedKycType rather than on an exact status match.
enum KycStatus { INITIATED = 'initiated', APPROVED = 'approved', REJECTED = 'rejected', INVALID = 'invalid' }

type KycDocument = { _id: string; title: string; value: string; type: KycType; requiredFields: DocumentField[] }

type DocumentField =
  | {
  key: string;
  type: 'number' | 'string' | 'date' | 'boolean' | 'email' | 'phone' | 'smile-identity-images';
  label: string;
  required: boolean;
  defaultValue?: string | number | boolean;
  regexp?: string;
  regexpFlags?: string;
  format?: string
}
  | {
  key: string;
  type: 'enum';
  label: string;
  required: boolean;
  options: { value: string; label: string }[];
  defaultValue?: string;
  regexp?: string;
  regexpFlags?: string;
  format?: string
};

// One KYC rule for a country. Per-order when min/max are set, aggregate when
// maxAmountUsd/maxOrdersCount are set, and possibly both at once.
type KycSetting = {
  operationType: OperationType;
  currencyType: CurrencyType;
  type: KycType;                  // the tier this rule demands
  min?: number;                   // per-order USD floor, inclusive
  max?: number | 'Infinity';      // per-order USD ceiling, exclusive
  maxOrdersCount?: number;        // lifetime successful order count
  maxAmountUsd?: number;          // lifetime successful USD volume
};

Limits

Returned by Get limits.

type LimitRule = {
  id: string;
  criteria?: LimitCriteria; // AND of filters; omitted field is a wildcard
  limit: Limit;
};

type LimitCriteria = {
  side?: LimitSide;
  asset?: LimitAsset;
  paymentChannel?: string;
  currencyCode?: string;
  countryIsoCode?: string;
  merchantId?: string;
};

type Limit =
  | { type: 'per_tx_range'; value: { min?: number; max?: number } }
  | { type: 'window_volume'; accumulator: LimitAccumulator; window: LimitWindow; value: { max: number } }
  | { type: 'window_count';  accumulator: LimitAccumulator; window: LimitWindow; value: { max: number } };

enum LimitSide {
  DEPOSIT = 'deposit', // measured before fees
  PAYOUT = 'payout',   // measured after fees
}

enum LimitAsset {
  FIAT = 'fiat',
  CRYPTO = 'crypto',
  BALANCE = 'balance',   // a merchant balance moving for a user
  TREASURY = 'treasury', // a merchant funding or draining its own balance
}

enum LimitAccumulator { PLATFORM = 'platform', USER = 'user', MERCHANT = 'merchant' }

enum LimitWindow { DAILY = 'daily', WEEKLY = 'weekly', MONTHLY = 'monthly' }