Accepting mobile money in Go

Install

Go is served by the Go client. There is no Go-specific package, and this page does not pretend otherwise: what is below is that client, used the way Go is written.

go get github.com/ultraner/ultraner-go

The snippets below are checked in CI against the API's own schemas. This client is not yet driven end to end against the sandbox the way the Node one is.

The Go trap

`io.ReadAll(r.Body)` can only be done once. Read it into a slice, verify that slice, then unmarshal from the same bytes.

Taking a payment

Two things this shows that are easy to get wrong anywhere. The amount is in whole units for most African currencies, so 5000 TZS is five thousand shillings and not fifty. And provideris the network's provider code, not its brand name: Mixx by Yas is still Tigo on the wire.

package main

import (
    "os"
    "github.com/google/uuid"
    "github.com/ultraner/ultraner-go"
)

client := ultraner.New(os.Getenv("ULTRANER_API_KEY"))

payment, err := client.Payments.CreateMnoCharge(ctx, ultraner.MnoChargeParams{
    Amount:        5000,          // whole shillings: TZS has no minor unit
    Currency:      "TZS",
    Provider:      "Vodacom",     // provider code, not brand name
    AccountNumber: "255700000000",
}, ultraner.WithIdempotencyKey(uuid.NewString()))
if err != nil {
    return err
}
// Accepted, not paid.
log.Printf("reference=%s status=%s", payment.Reference, payment.Status)

The response means the request was accepted, not that money moved. A mobile-money charge sends a prompt to the payer's handset and they may take a minute, or never answer. Which is why the next section is not optional.

Receiving the result

The webhook is how you learn a payment succeeded. Verify the signature over the raw bytes before trusting anything in the payload, acknowledge quickly, and do the work afterwards: a slow handler gets retried, and retries mean you will see the same event twice.

func ultranerWebhook(w http.ResponseWriter, r *http.Request) {
    // Read once, keep the bytes: you verify and unmarshal the same slice.
    raw, err := io.ReadAll(r.Body)
    if err != nil {
        w.WriteHeader(http.StatusBadRequest)
        return
    }

    mac := hmac.New(sha256.New, []byte(os.Getenv("ULTRANER_WEBHOOK_SECRET")))
    mac.Write(raw)
    expected := hex.EncodeToString(mac.Sum(nil))

    // hmac.Equal is constant time; a == comparison is not.
    if !hmac.Equal([]byte(r.Header.Get("X-Ultraner-Signature")), []byte(expected)) {
        w.WriteHeader(http.StatusBadRequest)
        return
    }

    var event Event
    _ = json.Unmarshal(raw, &event)
    w.WriteHeader(http.StatusOK)   // acknowledge first
    go handle(event)               // then work
}