Go SDK

go get github.com/kraftonnotgar-spec/teepay-Go

import teepay "github.com/kraftonnotgar-spec/teepay-Go"

ctx := context.Background()

client, err := teepay.NewClient(os.Getenv("TEEPAY_API_KEY")) // or NewClient("") to read TEEPAY_API_KEY
if err != nil {
	log.Fatal(err)
}

caps, err := client.Capabilities(ctx)
if err != nil {
	log.Fatal(err)
}
fmt.Println(caps.Environment, caps.Features.CollectionCreate, caps.SupportedCurrencies)

payment, err := client.Collections.Create(ctx, &teepay.CollectionCreateParams{
	Money:          teepay.Money{AmountMinor: "500000", Currency: "TZS"}, // TZS 5,000.00
	Customer:       teepay.CollectionCustomer{Country: "TZ", Phone: "+255712345678", Name: "Asha Juma"},
	Description:    "Order 1001",
	IdempotencyKey: "order-1001",
})
if err != nil {
	return err
}
fmt.Println(payment.PublicReference, payment.Status) // "TP8K2M4QZ1" "pending"

// 202 means the prompt was sent, not that the customer paid.
// Wait for the payment.completed webhook, or poll:
latest, err := client.Collections.Retrieve(ctx, payment.PublicReference)
if err == nil && latest.Status == teepay.StatusSucceeded {
	fulfilOrder()
}

session, err := client.CheckoutSessions.Create(ctx, &teepay.CheckoutSessionCreateParams{
	Title:          "Order 1001",
	Description:    "2 x Coffee bag",
	AmountMinor:    "500000",
	Currency:       "TZS",
	Reference:      "order-1001",
	Metadata:       map[string]string{"cart": "c-77"},
	IdempotencyKey: "checkout-order-1001",
})
if err != nil {
	return err
}
http.Redirect(w, r, session.CheckoutURL, http.StatusSeeOther)

// Later: status becomes "paid" only after TeePay verified the payment.
session, err = client.CheckoutSessions.Retrieve(ctx, session.ID)
if err == nil && session.Status == teepay.CheckoutSessionStatusPaid {
	fmt.Println(session.Payment.Reference)
}

number, err := client.ControlNumbers.Create(ctx, &teepay.ControlNumberCreateParams{
	Kind:           teepay.ControlNumberKindBill,
	Customer:       teepay.ControlNumberCustomer{Name: "Asha Juma", Phone: "0712345678"},
	Description:    "School fees, term 1",
	AmountMinor:    "5000000",
	IdempotencyKey: "invoice-2026-0077",
})
if err == nil && number.LastResponse.StatusCode == 202 { // still being issued
	// call Create again later with the SAME IdempotencyKey
}

quote, err := client.Disbursements.Quote(ctx, &teepay.PayoutQuoteParams{
	Money:       teepay.PayoutMoney{Amount: 2500000, Currency: "TZS"},
	Destination: teepay.MobileDestination("Juma Ali", "255712345678"),
	Narration:   "Supplier payment October",
})
if err != nil {
	return err
}
payout, err := client.Disbursements.Create(ctx, &teepay.PayoutCreateParams{
	QuoteID:        quote.ID,
	IdempotencyKey: "payout-2026-10-0001",
})

page, err := client.Collections.List(ctx, &teepay.TransactionListParams{Limit: 50, Status: teepay.StatusSucceeded})
if err != nil {
	return err
}
for _, item := range page.Items {
	fmt.Println(item.PublicReference)
}

it := client.Collections.ListAll(ctx, &teepay.TransactionListParams{Status: teepay.StatusSucceeded}) // follows next_cursor
for it.Next() {
	fmt.Println(it.Current().PublicReference)
}
if err := it.Err(); err != nil {
	return err
}

http.HandleFunc("POST /webhooks/teepay", func(w http.ResponseWriter, r *http.Request) {
	payload, err := io.ReadAll(io.LimitReader(r.Body, 1<<20)) // the raw body, before any JSON decoding
	if err != nil {
		http.Error(w, "bad request", http.StatusBadRequest)
		return
	}
	event, err := teepay.VerifyWebhook(payload, r.Header, os.Getenv("TEEPAY_WEBHOOK_SECRET"))
	if err != nil { // *teepay.WebhookVerificationError
		http.Error(w, "invalid signature", http.StatusBadRequest)
		return
	}
	if event.Event == teepay.EventPaymentCompleted {
		markPaid(event.Data.Reference) // de-duplicate on event.ID
	}
	w.WriteHeader(http.StatusOK)
})

_, err := client.Collections.Create(ctx, params)

var (
	invalid    *teepay.ValidationError
	restricted *teepay.AccountRestrictedError
	denied     *teepay.PermissionError
	limited    *teepay.RateLimitError
	conn       *teepay.ConnectionError
	apiErr     *teepay.APIError
)
switch {
case errors.As(err, &invalid): // 422: Code is invalid_request, unsupported_market, invalid_amount, ...
	log.Println(invalid.Code, invalid.Message)
case errors.As(err, &restricted): // 403 account_restricted: contact TeePay support
case errors.As(err, &denied): // 403 scope_denied / access_denied
case errors.As(err, &limited): // 429 after retries; wait limited.RetryAfter
case errors.As(err, &conn): // network error or timeout: the payment may still exist
	// retry with the SAME idempotency key, or read it
case errors.As(err, &apiErr): // anything else, e.g. 503
	log.Println(apiErr.StatusCode, apiErr.Code, apiErr.RequestID)
}

client, err := teepay.NewClient("", teepay.WithTimeout(20*time.Second), teepay.WithMaxRetries(3))

// Per request:
client.Collections.Retrieve(ctx, "TP8K2M4QZ1",
	teepay.WithRequestTimeout(5*time.Second), teepay.WithRequestMaxRetries(0))

// A context deadline bounds the whole call, retries included:
ctx, cancel := context.WithTimeout(ctx, 45*time.Second)
defer cancel()

payment, err := client.Collections.Create(ctx, params)
info := payment.LastResponse
info.StatusCode         // 202
info.RequestID          // for support
info.RateLimit          // &RateLimit{Limit: 120, Remaining: 117, Reset: 42}
info.IdempotentReplayed // true when TeePay replayed an earlier result
info.APIVersion         // "2026-10-18"