@maxnate/provider-selcom

Selcom payment provider for @maxnate/payments-core.

Supports receiving payments only (collection). Disbursements are not part of this package.

Payment Types

| Type | paymentType | Currency | Flow | |---|---|---|---| | Mobile Money | "mobile" | TZS | Wallet cashin via USSD (M-Pesa, Airtel, Tigo, HaloPesa) | | Card | "card" | TZS | Redirect to Selcom Checkout |

Authentication

Selcom uses HMAC-SHA256 digest authentication. Every request requires:

• Authorization: SELCOM <Base64(apiKey)>
• Digest-Method: HS256
• Digest: Base64(HMAC_SHA256(signing_string, apiSecret))
• Timestamp in ISO 8601 format
• Signed-Fields listing parameter order

The provider handles all signing automatically.

Required credentials:

• apiKey — Provided by Selcom support
• apiSecret — For HMAC signing
• vendor — Float account identifier
• pin — Float account PIN

Usage

import { createPaymentProviderRegistry } from '@maxnate/payments-core'
import { SelcomProvider } from '@maxnate/provider-selcom'

const registry = createPaymentProviderRegistry()
registry.register(new SelcomProvider())

registry.setConfig({
  id: 'selcom',
  name: 'Selcom',
  type: 'mobile_money',
  enabled: true,
  credentials: {
    apiKey: process.env.SELCOM_API_KEY!,
    apiSecret: process.env.SELCOM_API_SECRET!,
    vendor: process.env.SELCOM_VENDOR!,
    pin: process.env.SELCOM_PIN!
  },
  currencies: ['TZS'],
  countries: ['TZ']
})

// Mobile Money
const result = await registry.createPaymentIntent('selcom', {
  orderId: 'ORD-001',
  amount: 5000,
  currency: 'TZS',
  paymentType: 'mobile',
  customerPhone: '255712345678',
  metadata: { walletProvider: 'mpesa' }
})

// Card
const cardResult = await registry.createPaymentIntent('selcom', {
  orderId: 'ORD-002',
  amount: 25000,
  currency: 'TZS',
  paymentType: 'card',
  customerEmail: '[email protected]'
})

INPROGRESS / AMBIGUOUS Handling

Selcom may return INPROGRESS (resultcode 111/927) or AMBIGUOUS (999) for pending transactions. Use waitForSettlement() to poll until resolved:

const provider = registry.get('selcom') as SelcomProvider
const settled = await provider.waitForSettlement('TXN...', 5)