Class: SelcomPaymentProvider

Defined in: providers/selcom/src/selcom.ts:87

Extends

BasePaymentProvider

Constructors

Constructor

new SelcomPaymentProvider(config): SelcomPaymentProvider;

Defined in: providers/selcom/src/selcom.ts:113

Parameters

Parameter	Type
`config`	`SelcomConfig`

Returns

SelcomPaymentProvider

Overrides

BasePaymentProvider.constructor

Properties

Property	Modifier	Type	Default value	Description	Overrides	Defined in
`name`	`readonly`	`ProviderName`	`'selcom'`	Unique provider identifier.	`BasePaymentProvider.name`	providers/selcom/src/selcom.ts:88

Methods

agentCashout()

agentCashout(
   msisdn, 
   amount, 
   name?): Promise<{
  message: string;
  reference: string;
  status: string;
  transid: string;
}>;

Defined in: providers/selcom/src/selcom.ts:868

Send funds to a customer for cash pickup at any Selcom Huduma agent.

The customer dials *150*50#, selects Huduma Cashout, enters the agent code and amount to complete the withdrawal.

Parameters

Parameter	Type	Description
`msisdn`	`string`	— customer mobile number (receives the cashout token).
`amount`	`number`	— amount in TZS.
`name?`	`string`	— customer name (optional).

Returns

Promise<{ message: string; reference: string; status: string; transid: string; }>

cancelOrder()

cancelOrder(orderId): Promise<{
  cancelled: boolean;
  message?: string;
  orderId: string;
}>;

Defined in: providers/selcom/src/selcom.ts:558

Cancel a pending or in-progress order.

Parameters

Parameter	Type
`orderId`	`string`

Returns

Promise<{ cancelled: boolean; message?: string; orderId: string; }>

Throws

PesaUnsupportedError — if the provider does not support cancellation.

Overrides

BasePaymentProvider.cancelOrder

checkoutWalletPayment()

checkoutWalletPayment(orderId, msisdn): Promise<{
  reference: string;
  status: string;
  transid: string;
}>;

Defined in: providers/selcom/src/selcom.ts:672

Trigger a USSD push from an existing checkout order.

Use this for in-app payments where the customer is already on your checkout page and you want to trigger a mobile money PIN prompt without redirecting to Selcom's payment gateway.

Parameters

Parameter	Type
`orderId`	`string`
`msisdn`	`string`

Returns

Promise<{ reference: string; status: string; transid: string; }>

createOrder()

createOrder(payload): Promise<OrderResult>;

Defined in: providers/selcom/src/selcom.ts:264

Initiate a checkout / USSD push / redirect.

The SDK calls validateCreateOrderPayload() before this, so you can assume amount > 0, reference is non-empty, and customer.phone is in MSISDN format.

Parameters

Parameter	Type
`payload`	`CreateOrderPayload`

Returns

Promise<OrderResult>

Overrides

BasePaymentProvider.createOrder

deleteStoredCard()

deleteStoredCard(id, gatewayBuyerUuid): Promise<{
  message: string;
  status: string;
}>;

Defined in: providers/selcom/src/selcom.ts:942

Delete a stored card token.

Parameters

Parameter	Type
`id`	`string`
`gatewayBuyerUuid`	`string`

Returns

Promise<{ message: string; status: string; }>

disburse()

disburse(payload): Promise<DisburseResult>;

Defined in: providers/selcom/src/selcom.ts:378

B2C / wallet-out disbursement.

The SDK calls validateDisbursePayload() before this.

Parameters

Parameter	Type
`payload`	`DisbursePayload`

Returns

Promise<DisburseResult>

Overrides

BasePaymentProvider.disburse

fetchStoredCards()

fetchStoredCards(gatewayBuyerUuid, buyerUserid): Promise<{
  cards: {
     cardToken: string;
     cardType: string;
     creationDate: string;
     id: string;
     maskedCard: string;
     name: string;
  }[];
}>;

Defined in: providers/selcom/src/selcom.ts:909

Fetch stored (tokenized) cards for a buyer.

Parameters

Parameter	Type	Description
`gatewayBuyerUuid`	`string`	— returned from the first create-order call for this buyer (`raw.data[0].gateway_buyer_uuid`).
`buyerUserid`	`string`	— your internal user ID for the buyer.

Returns

Promise<{ cards: { cardToken: string; cardType: string; creationDate: string; id: string; maskedCard: string; name: string; }[]; }>

getBalance()

getBalance(): Promise<BalanceResult>;

Defined in: providers/selcom/src/selcom.ts:602

Retrieve available balances across all active currencies.

Useful for dashboards, pre-disbursement checks, and wallet health monitoring. Returns per-currency balance entries with raw provider data for advanced use.

Returns

Promise<BalanceResult>

{ balances: [...] } with per-currency entries.

Throws

PesaUnsupportedError — if the provider does not expose balance data.

Since

0.2.0

Overrides

BasePaymentProvider.getBalance

getNameLookup()

getNameLookup(phoneOrAccount): Promise<NameLookupResult>;

Defined in: providers/selcom/src/selcom.ts:623

Resolve the account holder name for a phone or account number.

Useful for verifying recipient identity before disbursing.

Parameters

Parameter	Type
`phoneOrAccount`	`string`

Returns

Promise<NameLookupResult>

Throws

PesaUnsupportedError — if the provider does not support name lookup.

Overrides

BasePaymentProvider.getNameLookup

getPaymentStatus()

getPaymentStatus(orderId): Promise<PaymentStatus>;

Defined in: providers/selcom/src/selcom.ts:353

Poll or fetch the current payment status for an order.

Parameters

Parameter	Type
`orderId`	`string`

Returns

Promise<PaymentStatus>

Overrides

BasePaymentProvider.getPaymentStatus

handleWebhook()

handleWebhook(rawBody, headers): Promise<PaymentEvent>;

Defined in: providers/selcom/src/selcom.ts:485

Parse + verify an incoming webhook.

The provider must:

Verify its own cryptographic signature (HMAC, checksum, etc.)
Parse the raw body into structured data
Return a normalized PaymentEvent

The SDK handles UUID assignment, event persistence, plugin hooks, and user-registered handler emission after this method returns.

Parameters

Parameter	Type
`rawBody`	`string` \| `Buffer`<`ArrayBufferLike`>
`headers`	`Record`<`string`, `string`>

Returns

Promise<PaymentEvent>

Overrides

BasePaymentProvider.handleWebhook

listOrders()

listOrders(params): Promise<ListOrdersResult>;

Defined in: providers/selcom/src/selcom.ts:572

List payment orders for a date range.

Parameters

Parameter	Type
`params`	`ListOrdersParams`

Returns

Promise<ListOrdersResult>

Throws

PesaUnsupportedError — if the provider does not support listing orders.

Overrides

BasePaymentProvider.listOrders

lookupUtility()

lookupUtility(utilitycode, utilityref): Promise<{
  data: unknown[];
  message: string;
  reference: string;
  status: string;
  transid: string;
}>;

Defined in: providers/selcom/src/selcom.ts:743

Look up a utility account before payment.

Returns the account holder name and (for some utilities) amount due.

Parameters

Parameter	Type
`utilitycode`	`string`
`utilityref`	`string`

Returns

Promise<{ data: unknown[]; message: string; reference: string; status: string; transid: string; }>

payUtility()

payUtility(params): Promise<{
  message: string;
  reference: string;
  status: string;
  transid: string;
}>;

Defined in: providers/selcom/src/selcom.ts:705

Pay a utility bill (electricity, water, TV, airtime, etc.).

Parameters

Parameter	Type
`params`	{ `amount`: `number`; `msisdn?`: `string`; `utilitycode`: `string`; `utilityref`: `string`; }
`params.amount`	`number`
`params.msisdn?`	`string`
`params.utilitycode`	`string`
`params.utilityref`	`string`

Returns

Promise<{ message: string; reference: string; status: string; transid: string; }>

previewDisburse()?

optional previewDisburse(_payload): Promise<PreviewResult>;

Defined in: packages/pesa/dist/providers/base.d.ts:139

Preview / dry-run a disbursement before committing.

Parameters

Parameter	Type
`_payload`	`DisbursePayload`

BasePaymentProvider.previewDisburse

previewOrder()?

optional previewOrder(_payload): Promise<PreviewResult>;

Defined in: packages/pesa/dist/providers/base.d.ts:133

Preview / dry-run a payment before committing.

Returns expected fees and validity without charging the customer.

Parameters

Parameter	Type
`_payload`	`CreateOrderPayload`

BasePaymentProvider.previewOrder

queryUtilityStatus()

queryUtilityStatus(transid): Promise<{
  data: unknown[];
  message: string;
  reference: string;
  status: string;
}>;

Defined in: providers/selcom/src/selcom.ts:772

Query the status of a utility payment.

Parameters

Parameter	Type
`transid`	`string`

Returns

Promise<{ data: unknown[]; message: string; reference: string; status: string; }>

refund()?

optional refund(_orderId, _amount?): Promise<RefundResult>;

Defined in: packages/pesa/dist/providers/base.d.ts:94

Refund a completed payment.

Parameters

Parameter	Type
`_orderId`	`string`
`_amount?`	`number`

BasePaymentProvider.refund

selcomPesaCashin()

selcomPesaCashin(
   utilityref, 
   amount, 
   msisdn?): Promise<{
  message: string;
  reference: string;
  status: string;
  transid: string;
}>;

Defined in: providers/selcom/src/selcom.ts:799

Send funds to a Selcom Pesa account.

Parameters

Parameter	Type	Description
`utilityref`	`string`	— Selcom Pesa account number or mobile number.
`amount`	`number`	— amount in TZS.
`msisdn?`	`string`	— sender mobile number (optional).

Returns

Promise<{ message: string; reference: string; status: string; transid: string; }>

selcomPesaNameLookup()

selcomPesaNameLookup(utilityref): Promise<{
  message: string;
  name?: string;
  reference: string;
  status: string;
  transid: string;
}>;

Defined in: providers/selcom/src/selcom.ts:833

Look up a Selcom Pesa account holder name.

Parameters

Parameter	Type
`utilityref`	`string`

Returns

Promise<{ message: string; name?: string; reference: string; status: string; transid: string; }>

validateCredentials()

validateCredentials(): Promise<{
  message?: string;
  valid: boolean;
}>;

Defined in: providers/selcom/src/selcom.ts:644

Validate that a provider config works (health check).

Useful for startup checks or /health endpoints.

BasePaymentProvider.validateCredentials

Class: SelcomPaymentProvider

On this page