DIGIHCE SDK Documentation

dependencyResolutionManagement {
    repositories {
        maven {
            url = uri("https://maven.hce.vas.et/releases")
            credentials {
                username = "token"
                password = providers.gradleProperty("DIGIHCE_TOKEN").get()
            }
        }
    }
}

dependencies {
    implementation("com.digihce:sdk:1.0.0")
}

class SampleApp : Application() {
    override fun onCreate() {
        super.onCreate()

        DigiHceSdk.init(applicationContext) {
            apiKey = "digi_live_xxxxxxxxxxxx"
            aid = "F0746C6272507961"        // optional, uses default
            environment = Environment.SANDBOX // or PRODUCTION
            cardIdentity = CardIdentity(
                name = "User A",
                accountId = "ACC-12345",
                msisdn = "+251912345678"     // optional, for USSD 2FA
            )
            cardEnabled = true
        }
    }
}

val reader = DigiHceSdk.createReader(activity)

// Start collecting — returns a Flow scoped to this session
val sessionFlow: Flow<DigiHceEvent> = reader.collect(
    amount = "100.00",
    currency = "ETB"
)

// Observe events
sessionFlow.collect { event ->
    when (event) {
        is DigiHceEvent.ChargeCompleted -> {
            showSuccess(event.result)
        }
        is DigiHceEvent.ChargePending2FA -> {
            showWaiting("Awaiting USSD confirmation...")
        }
        is DigiHceEvent.TransactionReversed -> {
            showReversed(event.reason)
        }
        is DigiHceEvent.Error -> {
            showError(event.error)
        }
    }
}

// Stop when done
reader.stop()

// Prepare server-signed payment payload
val result: Result<TransactionResult> = DigiHceSdk.preparePayment(
    amount = "50.00",
    currency = "ETB"
)

when {
    result.isSuccess -> {
        // HCE now broadcasts the signed payload
        // On tap + CONFIRM → emits PaymentSent
        showReady("Tap to send payment")
    }
    result.isFailure -> {
        showError(result.exceptionOrNull())
    }
}

// Cancel if needed
DigiHceSdk.cancelPayment()

DigiHceSdk.events.collect { event ->
    when (event) {
        is DigiHceEvent.ChargeReceived -> { }
        is DigiHceEvent.ChargePending2FA -> { }
        is DigiHceEvent.ChargeCompleted -> { }
        is DigiHceEvent.PaymentSent -> { }
        is DigiHceEvent.PaymentReceived -> { }
        is DigiHceEvent.TransactionReversed -> { }
        is DigiHceEvent.Error -> { }
        is DigiHceEvent.SdkDeactivated -> { }
    }
}

DigiHceSdk.setListener(object : DigiHceListener {
    override fun onChargeReceived(result: TransactionResult) {}
    override fun onChargePending2FA(transactionId: String) {}
    override fun onChargeCompleted(result: TransactionResult) {}
    override fun onPaymentSent(result: TransactionResult) {}
    override fun onPaymentReceived(result: TransactionResult) {}
    override fun onTransactionReversed(id: String, reason: String) {}
    override fun onError(error: DigiHceError) {}
    override fun onSdkDeactivated(reason: String) {}
})

data class CardIdentity(
    val name: String,
    val accountId: String,
    val msisdn: String? = null   // for USSD 2FA
)

data class TransactionResult(
    val transactionId: String,
    val status: TransactionStatus,
    val amount: String,
    val currency: String,
    val counterparty: String,
    val timestamp: Long,
    val serverReceipt: String?
)

enum class TransactionStatus {
    SETTLED,
    PENDING_2FA,
    REVERSED,
    FAILED,
    PENDING_SYNC     // offline payer, awaiting connectivity
}

curl https://api.hce.vas.et/v1/pg/transactions?status=settled&per_page=50   -H "X-API-Key: digi_live_..."

{
  "id": "dlv_3f9a1c7e2b4d6a80",
  "event": "transaction.settled",
  "timestamp": "2026-11-01T09:30:12.418Z",
  "payment_gateway_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "data": {
    "transactionId": "txn_9c3e7b1a2f4d5e6c",
    "type": "charge",
    "amount": "250.00",
    "currency": "ETB",
    "receipt": "...",
    "settledAt": "2026-11-01T09:30:12.401Z",
    "payerAccountId": "...",
    "payerName": "...",
    "pinVerified": true,
    "pinMethod": "client_side_pin_v1"
  }
}

const crypto = require("crypto");

// webhookSecret: the whsec_... value shown once when you added or rotated the endpoint.
function verifyDigiHce(rawBody, headers, webhookSecret) {
  const key = crypto.createHash("sha256").update(webhookSecret).digest("hex");
  const ts = headers["x-digihce-timestamp"];
  if (!ts || Math.abs(Date.now() - Date.parse(ts)) > 5 * 60 * 1000) return false;
  const expected =
    "sha256=" + crypto.createHmac("sha256", key).update(`${ts}.${rawBody}`).digest("hex");
  const got = headers["x-digihce-signature-256"] ?? "";
  return got.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

sealed class DigiHceError {
    data class AuthFailed(val message: String) : DigiHceError()
    data class NfcUnavailable(val message: String) : DigiHceError()
    data class TransactionFailed(
        val transactionId: String?,
        val message: String
    ) : DigiHceError()
    data class NetworkError(val message: String) : DigiHceError()
    data class LicenseExpired(val message: String) : DigiHceError()
    data class CardDisabled(val message: String) : DigiHceError()
}