Core
@sompaykit/core: phone numbers, wallets, USSD codes and payment providers. Zero dependencies.
npm install @sompaykit/coreRuns 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
});| Provider | Mode | Status |
|---|---|---|
manual | Customer sends money, types transaction ID | Ready |
waafipay | PIN prompt on the customer's phone | Coming (waiting for sandbox access) |
sifalopay | Payment page: customer pays on SifaloPay | Ready 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
| Status | Meaning | Final |
|---|---|---|
pending | Automatic mode: waiting for the customer's PIN | No |
awaiting_proof | Manual mode: waiting for the customer to pay | No |
awaiting_confirmation | Manual mode: transaction ID sent, merchant to check | No |
paid | Paid | Yes |
failed | Declined, cancelled, no balance… see errorCode | Yes |
expired | Not paid in time | Yes |
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…'); // PaymentStatusIn 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.
| Prefix | Wallet | Operator |
|---|---|---|
61, 77 | EVC Plus | Hormuud |
63 | Zaad | Telesom |
90 | Sahal | Golis |
62, 65 | eDahab | Somtel |
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
}
}| Code | When |
|---|---|
INSUFFICIENT_FUNDS | Not enough balance |
DECLINED | The wallet declined |
CANCELLED | The customer cancelled the PIN prompt |
TIMEOUT | No PIN in time |
NETWORK_ERROR | No connection to your server or the gateway |
PROVIDER_ERROR | The gateway returned something unexpected |
INVALID_NUMBER | Not a Somali mobile number |
INVALID_AMOUNT | Not positive, over 1,000,000, or more than 2 decimals |
INVALID_CURRENCY | Not USD or SLSH |
INVALID_REFERENCE | Missing or badly formed referenceId |
WALLET_REQUIRED | No wallet given and none detected |
WALLET_NOT_SUPPORTED | The provider or merchant doesn't take it |
DUPLICATE_REFERENCE | Same referenceId, different payment |
NOT_FOUND | Unknown referenceId |
NOT_IMPLEMENTED | Provider not available yet |
METHOD_NOT_SUPPORTED | charge on a payment page, or checkout without one |
AMOUNT_MISMATCH | Payment page: paid, but not the order's amount |
CONFIG_ERROR | Missing keys or bad options |