Skip to content
Test money only. BitMomo currently runs on test networks. Payments use testnet coins and no real money moves. Live keys are not available yet.

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.

Terminal window
go get go.bitmomo.app/merchant
import bitmomo "go.bitmomo.app/merchant"
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. Plain http:// is accepted only for localhost.
  • The client never follows redirects, so your key is never sent to another host. This also applies when you pass your own *http.Client with bitmomo.WithHTTPClient.
  • A *bitmomo.Client is safe for concurrent use. Other options: WithMaxRetries(n).
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)
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.

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 parsing
if 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 2xx

See Webhooks for the full flow.

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 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.