Go SDK
go.bitmomo.app/merchant is the official Go SDK. It needs Go 1.22 or later, uses only the standard library, and takes a context.Context on every call. The package is named bitmomo.
go get go.bitmomo.app/merchantimport bitmomo "go.bitmomo.app/merchant"Configure a client
Section titled “Configure a client”client, err := bitmomo.NewClient( os.Getenv("BITMOMO_API_KEY"), "https://api.dev.bitmomo.app", bitmomo.WithTimeout(10*time.Second),)if err != nil { log.Fatal(err)}- The base URL is required. It must be an
https://origin with no path, query, fragment or credentials. Plainhttp://is accepted only forlocalhost. - The client never follows redirects, so your key is never sent to another host. This also applies when you pass your own
*http.Clientwithbitmomo.WithHTTPClient. - A
*bitmomo.Clientis safe for concurrent use. Other options:WithMaxRetries(n).
Create a payment
Section titled “Create a payment”payment, err := client.CreatePayment(ctx, bitmomo.CreatePaymentParams{ Amount: "100.00", // Ghana cedis, as an exact decimal CryptoType: "USDT_TRC20", OrderID: "order_1001", IdempotencyKey: bitmomo.NewIdempotencyKey(), // store this with the order first})if err != nil { return err}fmt.Println(payment.ID, payment.CryptoAmount, payment.DepositAddress, payment.QRCodeData)Methods
Section titled “Methods”| Method | Endpoint | Scope |
|---|---|---|
CreatePayment(ctx, CreatePaymentParams) |
POST /gateway/payments |
payments:write |
GetPayment(ctx, id) |
GET /gateway/payments/{id} |
payments:read |
ListPayments(ctx, ListPaymentsParams) |
GET /gateway/payments |
payments:read |
GetBalances(ctx) |
GET /gateway/balances |
payments:read |
RequestPayout(ctx, PayoutParams) |
POST /gateway/payouts |
payouts:write |
GetWebhookConfig(ctx) |
GET /gateway/webhooks/config |
webhooks:read |
UpdateWebhookConfig(ctx, UpdateWebhookConfigParams) |
PUT /gateway/webhooks/config |
webhooks:write |
DeleteWebhookConfig(ctx) |
DELETE /gateway/webhooks/config |
webhooks:write |
RotateWebhookSecret(ctx) |
POST /gateway/webhooks/config/rotate |
webhooks:write |
CreatePaymentLink(ctx, CreatePaymentLinkParams) |
POST /gateway/payment-links |
payments:write |
ListPaymentLinks(ctx) |
GET /gateway/payment-links |
payments:read |
GetPaymentLink(ctx, id) |
GET /gateway/payment-links/{id} |
payments:read |
GetPaymentStatus(ctx, id) |
GET /payments/{id}/status |
none (public) |
GetRates(ctx) |
GET /rates |
none (public) |
Optional response fields are pointers (nil when absent). For optional boolean and number inputs, use the bitmomo.Bool and bitmomo.Float64 helpers.
RequestPayout requires IdempotencyKey; create it with bitmomo.NewIdempotencyKey(), save it, and reuse it on retries. Without one, the SDK refuses to send the request.
Webhook helpers
Section titled “Webhook helpers”| Helper | Use |
|---|---|
bitmomo.VerifyWebhookEvent(rawBody, signature, VerifyWebhookOptions) |
Full verification: signature, freshness and signed headers. Returns the envelope, or a *bitmomo.WebhookVerificationError whose Reason says why. |
bitmomo.VerifyWebhookSignature(rawBody, signature, secret) |
Signature check only. Prefer VerifyWebhookEvent. |
bitmomo.NewDeliveryDedupeCache(ttl) |
In-memory, concurrency-safe duplicate filter: Seen(deliveryID) returns true for a repeat (0 means 24 hours). Use a database for anything that matters. |
body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20)) // the raw bytes, before any JSON parsingif err != nil { http.Error(w, "read error", http.StatusBadRequest) return}env, err := bitmomo.VerifyWebhookEvent(body, r.Header.Get("X-Webhook-Signature"), bitmomo.VerifyWebhookOptions{ Secrets: []bitmomo.WebhookSecret{{Version: 1, Secret: os.Getenv("BITMOMO_WEBHOOK_SECRET")}}, Timestamp: r.Header.Get("X-Webhook-Timestamp"), KeyVersion: r.Header.Get("X-Webhook-Key-Version"),})if err != nil { http.Error(w, err.Error(), http.StatusBadRequest) // e.g. "bitmomo: webhook rejected: stale-timestamp" return}_ = env.DeliveryID // store the event durably under this ID, then reply 2xxSee Webhooks for the full flow.
Errors and retries
Section titled “Errors and retries”API failures are a *bitmomo.Error (use errors.As) with Status, Code, Message, RequestID and Retriable. Status is 0 when no response arrived (NETWORK_ERROR, which wraps the cause, including context cancellation) or the response broke the contract (SCHEMA_ERROR). Reads retry up to 3 times in total on 429 and 5xx, honouring Retry-After up to 60 seconds. Writes are never retried automatically; see Errors.
Money values
Section titled “Money values”Money is bitmomo.Decimal, a string holding an exact decimal such as "100.00"; it never passes through float64. Compare or add amounts with math/big (new(big.Rat).SetString(string(d))) or a decimal library. On balances, use the *Exact fields; the float64 fields are for display only.
- Package documentation: pkg.go.dev/go.bitmomo.app/merchant
- Source: github.com/samuel-1-avson/bitmomo-go
- SDK changelog