Integrating Fonepay with Go — QR, Web Redirect

package fonepay
 
import (
	"crypto/hmac"
	"crypto/sha512"
	"encoding/hex"
)
 
// Sign returns the lowercase-hex HMAC-SHA512 of message, keyed by secret.
func Sign(secret, message string) string {
	mac := hmac.New(sha512.New, []byte(secret))
	mac.Write([]byte(message))
	return hex.EncodeToString(mac.Sum(nil))
}
 
// SafeHexEqual compares two hex signatures in constant time.
// Never use `a == b` on the raw strings — that short-circuits and leaks timing.
func SafeHexEqual(a, b string) bool {
	ba, err1 := hex.DecodeString(a)
	bb, err2 := hex.DecodeString(b)
	if err1 != nil || err2 != nil || len(ba) == 0 {
		return false
	}
	return hmac.Equal(ba, bb) // false (constant-time) if lengths differ
}

package fonepay
 
import "os"
 
type Config struct {
	PGBaseURL    string // https://dev-clientapi.fonepay.com
	QRBaseURL    string // https://uat-new-merchant-api.fonepay.com/api
	MerchantCode string // PID
	Secret       string // never sent in any payload
	Username     string
	Password     string
	ReturnURL    string // public HTTPS callback
}
 
func FromEnv() Config {
	return Config{
		PGBaseURL:    os.Getenv("FONEPAY_PG_URL"),
		QRBaseURL:    os.Getenv("FONEPAY_QR_URL"),
		MerchantCode: os.Getenv("FONEPAY_MERCHANT_CODE"),
		Secret:       os.Getenv("FONEPAY_SECRET"),
		Username:     os.Getenv("FONEPAY_USERNAME"),
		Password:     os.Getenv("FONEPAY_PASSWORD"),
		ReturnURL:    os.Getenv("FONEPAY_RETURN_URL"),
	}
}

# Sandbox hosts — swap for the live hosts in production.
FONEPAY_PG_URL=https://dev-clientapi.fonepay.com
FONEPAY_QR_URL=https://uat-new-merchant-api.fonepay.com/api
 
FONEPAY_MERCHANT_CODE=NBQM
FONEPAY_SECRET=your_merchant_secret_key
FONEPAY_USERNAME=your_username
FONEPAY_PASSWORD=your_password
FONEPAY_RETURN_URL=https://your-tunnel.example.com/payments/fonepay/return

package fonepay
 
import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"net/http"
)
 
type QRResult struct {
	QRMessage    string `json:"qrMessage"` // encode THIS as the QR image
	WebSocketURL string `json:"thirdpartyQrWebSocketUrl"`
	StatusCode   int    `json:"statusCode"`
}
 
func (c Config) CreateDynamicQR(ctx context.Context, prn string, amount int, remarks1, remarks2 string) (*QRResult, error) {
	// EXACT order: amount, prn, merchantCode, remarks1, remarks2
	msg := fmt.Sprintf("%d,%s,%s,%s,%s", amount, prn, c.MerchantCode, remarks1, remarks2)
 
	body, _ := json.Marshal(map[string]any{
		"amount":         amount,
		"remarks1":       remarks1,
		"remarks2":       remarks2,
		"prn":            prn,
		"merchantCode":   c.MerchantCode,
		"dataValidation": Sign(c.Secret, msg),
		"username":       c.Username,
		"password":       c.Password,
	})
 
	url := c.QRBaseURL + "/merchant/merchantDetailsForThirdParty/thirdPartyDynamicQrDownload"
	req, _ := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
	req.Header.Set("Content-Type", "application/json")
 
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK && res.StatusCode != http.StatusCreated {
		return nil, fmt.Errorf("qr download failed: HTTP %d", res.StatusCode)
	}
 
	var out QRResult
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		return nil, err
	}
	return &out, nil
}

package fonepay
 
import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"net/http"
)
 
type QRStatus struct {
	PaymentStatus  string `json:"paymentStatus"` // "success" | "pending" | "failed"
	FonepayTraceID int64  `json:"fonepayTraceId"`
	PRN            string `json:"prn"`
}
 
func (c Config) GetQRStatus(ctx context.Context, prn string) (*QRStatus, error) {
	// EXACT order: prn, merchantCode
	dv := Sign(c.Secret, fmt.Sprintf("%s,%s", prn, c.MerchantCode))
 
	body, _ := json.Marshal(map[string]any{
		"prn":            prn,
		"merchantCode":   c.MerchantCode,
		"dataValidation": dv,
		"username":       c.Username,
		"password":       c.Password,
	})
 
	url := c.QRBaseURL + "/merchant/merchantDetailsForThirdParty/thirdPartyDynamicQrGetStatus"
	req, _ := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
	req.Header.Set("Content-Type", "application/json")
 
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("qr status failed: HTTP %d", res.StatusCode)
	}
 
	var out QRStatus
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		return nil, err
	}
	return &out, nil
}

package fonepay
 
import (
	"fmt"
	"net/url"
	"strconv"
	"strings"
	"time"
)
 
func (c Config) BuildPaymentURL(prn string, amount int, remarks1, remarks2 string) string {
	dt := time.Now().Format("01/02/2006") // MM/DD/YYYY
	amt := strconv.Itoa(amount)
 
	// Sign the RAW values in this EXACT order, THEN encode for transport.
	dv := Sign(c.Secret, strings.Join([]string{
		c.MerchantCode, "P", prn, amt, "NPR", dt, remarks1, remarks2, c.ReturnURL,
	}, ","))
 
	q := url.Values{}
	for k, v := range map[string]string{
		"PID": c.MerchantCode, "MD": "P", "PRN": prn, "AMT": amt, "CRN": "NPR",
		"DT": dt, "R1": remarks1, "R2": remarks2, "RU": c.ReturnURL, "DV": dv,
	} {
		q.Set(k, v)
	}
	return fmt.Sprintf("%s/api/merchantRequest?%s", c.PGBaseURL, q.Encode())
}

package fonepay
 
import (
	"context"
	"encoding/xml"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"strconv"
)
 
type Verification struct {
	XMLName      xml.Name `xml:"response"`
	Amount       float64  `xml:"amount"`
	BankCode     string   `xml:"bankCode"`
	Message      string   `xml:"message"`
	ResponseCode string   `xml:"response_code"` // "successful" on success
	Success      bool     `xml:"success"`
	UniqueID     string   `xml:"uniqueId"`
}
 
func (c Config) VerifyTransaction(ctx context.Context, prn, bid, uid string, amount int) (*Verification, error) {
	amt := strconv.Itoa(amount)
	// EXACT order: PID,AMT,PRN,BID,UID
	dv := Sign(c.Secret, fmt.Sprintf("%s,%s,%s,%s,%s", c.MerchantCode, amt, prn, bid, uid))
 
	q := url.Values{}
	for k, v := range map[string]string{
		"PRN": prn, "PID": c.MerchantCode, "BID": bid, "AMT": amt, "UID": uid, "DV": dv,
	} {
		q.Set(k, v)
	}
 
	endpoint := fmt.Sprintf("%s/api/merchantRequest/verificationMerchant?%s", c.PGBaseURL, q.Encode())
	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
 
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("verification failed: HTTP %d", res.StatusCode)
	}
 
	raw, _ := io.ReadAll(res.Body)
	var v Verification
	if err := xml.Unmarshal(raw, &v); err != nil {
		return nil, err
	}
	return &v, nil
}

<response>
  <amount>100</amount>
  <txnAmount>100</txnAmount>
  <bankCode>BANK</bankCode>
  <initiator>98XXXXXXXX</initiator>
  <message>payment success</message>
  <response_code>successful</response_code>
  <statusCode>1</statusCode>
  <success>true</success>
  <uniqueId>202406201234567</uniqueId>
</response>

package main
 
import (
	"context"
	"net/http"
	"os"
	"time"
 
	"yourapp/fonepay"
)
 
// OrderStore is your DB layer. MarkPaid must be a single atomic statement —
// e.g. UPDATE orders SET status='PAID' WHERE id=$1 AND status='PENDING' —
// returning true only for the first caller that wins the row.
type OrderStore interface {
	ByPRN(prn string) (Order, error)
	MarkPaid(id, gatewayRef string) (bool, error)
	MarkFailed(id string) error
	Fulfil(id string) error
}
 
func HandleReturn(fp fonepay.Config, store OrderStore) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		q := r.URL.Query()
		order, err := store.ByPRN(q.Get("PRN"))
		if err != nil {
			http.Error(w, "unknown payment", http.StatusNotFound)
			return
		}
 
		base := os.Getenv("CLIENT_URL")
		if order.Status != "PENDING" { // refresh / retry safe
			redirect(w, r, base, order.Status)
			return
		}
 
		ctx, cancel := context.WithTimeout(r.Context(), 30*time.Second)
		defer cancel()
 
		// Source of truth — not the redirect query.
		v, err := fp.VerifyTransaction(ctx, order.PRN, q.Get("BID"), q.Get("UID"), order.ExpectedAmount)
		if err != nil || !v.Success || v.ResponseCode != "successful" {
			_ = store.MarkFailed(order.ID)
			redirect(w, r, base, "FAILED")
			return
		}
 
		// Re-check the paid amount against what we stored (reject under- AND overpay).
		if int(v.Amount) != order.ExpectedAmount {
			http.Error(w, "amount mismatch", http.StatusBadRequest)
			return
		}
 
		// Atomic: only the first caller flips PENDING -> PAID and fulfils.
		if won, _ := store.MarkPaid(order.ID, v.UniqueID); won {
			_ = store.Fulfil(order.ID) // runs once, ever
		}
		redirect(w, r, base, "PAID")
	}
}
 
func redirect(w http.ResponseWriter, r *http.Request, base, status string) {
	dest := base + "/payment/failed"
	if status == "PAID" {
		dest = base + "/payment/success"
	}
	http.Redirect(w, r, dest, http.StatusSeeOther)
}

package payments
 
import (
	"context"
	"crypto/rand"
	"encoding/hex"
)
 
// newPRN returns a unique reference number — no external uuid package needed.
func newPRN() string {
	b := make([]byte, 16)
	_, _ = rand.Read(b)
	return hex.EncodeToString(b)
}
 
// CreatePayment re-prices the order from YOUR data and persists the PRN +
// expected amount as the source of truth. The client never sends an amount.
func (s *Service) CreatePayment(ctx context.Context, orderID string) (prn string, amount int, err error) {
	order, err := s.orders.ByID(ctx, orderID)
	if err != nil {
		return "", 0, err
	}
 
	// Re-derive from line items in your DB; ignore any client-sent total.
	expected := 0
	for _, li := range order.LineItems {
		expected += li.UnitPrice * li.Qty
	}
 
	prn = newPRN()
	if err := s.orders.InitPayment(ctx, orderID, prn, expected); err != nil {
		return "", 0, err
	}
	return prn, expected, nil
}

UPDATE orders
   SET status = 'PAID', gateway_ref = $2
 WHERE id = $1 AND status = 'PENDING';
-- rows affected == 1  -> you won the race, fulfil now
-- rows affected == 0  -> someone already did, do nothing