SomPayKit

Core

@sompaykit/core: phone numbers, wallets, USSD codes and payment providers. Zero dependencies.

npm install @sompaykit/core

Runs in Node 20+, Bun, Deno, edge and serverless. It only uses fetch, and has no dependencies.

Server only for automatic providers

createSomPay() with a gateway provider holds your API keys. Call it from server code (API routes, server actions) and read keys from server environment variables. The helpers (normalizePhone, detectWallet, message…) are safe in the browser.

createSomPay

import { createSomPay } from '@sompaykit/core';

const sompay = createSomPay({
  provider: 'manual',
  merchantNumbers: { evc: '612345678', zaad: '634567890' }, // leave a wallet out to hide it
  expiryHours: 24, // optional: unconfirmed payments expire after this
});
ProviderModeStatus
manualCustomer sends money, types transaction IDReady
waafipayPIN prompt on the customer's phoneComing (waiting for sandbox access)
sifalopayPayment page: customer pays on SifaloPayReady on staging

manual and waafipay use charge and status. sifalopay uses checkout and verify. Calling the other pair throws METHOD_NOT_SUPPORTED.

charge

Starts a payment. Bad input throws a SomPayError before any payment is attempted. Payment outcomes (declined, timeout…) come back in the result.

const result = await sompay.charge({
  referenceId: 'spk_7f3a…', // 1–64 of A-Z a-z 0-9 _ . : -  — unique per attempt
  orderId: 'order_123', // optional, defaults to referenceId
  phone: '061 234 5678', // any common format
  amount: 18, // from your database
  currency: 'USD', // 'USD' | 'SLSH'
  wallet: 'evc', // optional: detected from the phone prefix if left out
  description: 'Order #123', // optional
});

Calling charge() again with the same referenceId returns the same payment instead of creating a second one.

Result

interface CreatePaymentResult {
  referenceId: string;
  status: PaymentStatus;
  providerTxnId?: string;
  instructions?: ManualInstructions; // manual mode only
  errorCode?: ErrorCode; // when status is 'failed'
  raw?: unknown; // gateway response, for disputes: never send it to the browser
}

Return toClientResult(result) from your API route: it drops raw.

Payment statuses

StatusMeaningFinal
pendingAutomatic mode: waiting for the customer's PINNo
awaiting_proofManual mode: waiting for the customer to payNo
awaiting_confirmationManual mode: transaction ID sent, merchant to checkNo
paidPaidYes
failedDeclined, cancelled, no balance… see errorCodeYes
expiredNot paid in timeYes

isFinalStatus(status) tells you when to stop polling.

Manual instructions

interface ManualInstructions {
  wallet: 'evc' | 'zaad' | 'sahal' | 'edahab';
  number: string; // merchant number, local form: '612345678'
  amount: number;
  currency: 'USD' | 'SLSH';
  ussdCode: string | null; // '*712*612345678*18#', or null if unknown for this wallet
  ussdLink: string | null; // 'tel:*712*612345678*18%23' for a "Dial to pay" button
}

Pass it straight to ManualPayCard.

status

const status = await sompay.status('spk_7f3a…'); // PaymentStatus

In manual mode your database is the source of truth: you set awaiting_confirmation when the customer sends a transaction ID and paid when you confirm it.

checkout and verify

The payment page: the buyer pays on SifaloPay's page (EVC, ZAAD, Sahal, eDahab, Premier or card) and comes back to your site. USD only.

const sompay = createSomPay({
  provider: 'sifalopay',
  apiUser: process.env.SIFALO_API_USER!,
  apiKey: process.env.SIFALO_API_KEY!,
  env: 'staging', // 'staging' | 'live'
});

const { redirectUrl } = await sompay.checkout({
  orderId: 'order_123', // added to returnUrl as order_id
  amount: 3, // from your database
  currency: 'USD',
  returnUrl: 'https://shop.example/checkout/return',
  webhookUrl: 'https://shop.example/api/sifalo-webhook',
});
// Send the buyer to redirectUrl.

The buyer comes back to returnUrl with order_id and sid in the query. Confirm on your server, there and in the webhook:

const result = await sompay.verify({ sid, amount: order.total });
// result.status: 'paid' | 'pending' | 'failed'   (failed has an errorCode)

Only verify can be trusted

The return URL and the webhook body are not signed. Mark an order paid only when verify returns paid. Always pass the order's amount from your database, and store each sid with a unique constraint so one payment can't unlock two orders.

If verify throws (TIMEOUT, NETWORK_ERROR, PROVIDER_ERROR), the state of the payment is unknown. Keep the order pending and try again. Gateway calls can take up to 120 seconds.

The sandbox only approves SifaloPay's test wallets (eDahab 621111111). Other numbers fail.

Phone numbers and wallets

import { detectWallet, maskPhone, normalizePhone, toNationalNumber } from '@sompaykit/core';

normalizePhone('+252 61 234 5678'); // '252612345678'
normalizePhone('0612345678'); // '252612345678'
normalizePhone('12'); // null
toNationalNumber('252612345678'); // '612345678'
maskPhone('252612345678'); // '252 61 *** 5678': safe for logs
detectWallet('63 123 4567'); // 'zaad'

Detection is a suggestion

Numbers can move between operators, so always let the customer pick another wallet. The prefix table and USSD codes are marked VERIFY in constants.ts until each operator confirms them.

PrefixWalletOperator
61, 77EVC PlusHormuud
63ZaadTelesom
90SahalGolis
62, 65eDahabSomtel

WALLETS has each wallet's name, operator and a short label; MOBILE_WALLETS lists the four phone wallets in display order.

USSD codes

import { buildUssdCode, ussdLink } from '@sompaykit/core';

const code = buildUssdCode('evc', '612345678', 18); // '*712*612345678*18#'
if (code) ussdLink(code); // 'tel:*712*612345678*18%23'

Only EVC Plus has a known pattern so far. Other wallets return null: show the number with a Copy button instead (ManualPayCard does this for you).

Errors

Every error has a stable code and a message in Somali, English and Arabic.

import { isSomPayError, message } from '@sompaykit/core';

try {
  await sompay.charge(input);
} catch (error) {
  if (isSomPayError(error)) {
    error.code; // 'INVALID_NUMBER'
    message(error.code, 'so'); // Somali text for the customer
  }
}
CodeWhen
INSUFFICIENT_FUNDSNot enough balance
DECLINEDThe wallet declined
CANCELLEDThe customer cancelled the PIN prompt
TIMEOUTNo PIN in time
NETWORK_ERRORNo connection to your server or the gateway
PROVIDER_ERRORThe gateway returned something unexpected
INVALID_NUMBERNot a Somali mobile number
INVALID_AMOUNTNot positive, over 1,000,000, or more than 2 decimals
INVALID_CURRENCYNot USD or SLSH
INVALID_REFERENCEMissing or badly formed referenceId
WALLET_REQUIREDNo wallet given and none detected
WALLET_NOT_SUPPORTEDThe provider or merchant doesn't take it
DUPLICATE_REFERENCESame referenceId, different payment
NOT_FOUNDUnknown referenceId
NOT_IMPLEMENTEDProvider not available yet
METHOD_NOT_SUPPORTEDcharge on a payment page, or checkout without one
AMOUNT_MISMATCHPayment page: paid, but not the order's amount
CONFIG_ERRORMissing keys or bad options