kkhay

README

kkhay-go

Official Go SDK for K Khay — The Non-Custodial Crypto Payment Gateway

Accept cryptocurrency payments across 190+ blockchain networks and 500+ tokens (EVM, Bitcoin, Solana, TON, Tron, and XRPL) with zero custody and automatic direct-to-wallet settlement. Built with zero external dependencies using the Go standard library.

Gateway Dashboard • API Keys • Website

---

⚡ Key Highlights

• 🛡️ 100% Non-Custodial: Payments settle directly to your destination blockchain address in seconds. K Khay never holds your private keys or customer funds.
• 🌐 190+ Networks Supported:
  • EVM Networks: Ethereum, BNB Smart Chain, Polygon, Arbitrum, Base, Optimism, Avalanche, and 180+ more.
  • UTXO Networks: Bitcoin (btc), Dogecoin (doge), Litecoin (ltc), Bitcoin Cash (bch).
  • High-Throughput Chains: Solana (sol), TON (ton), Tron (trx), XRP Ledger (xrp).
• 🪙 500+ Cryptocurrencies: Native coins and tokens (USDT, USDC, BTC, ETH, SOL, TON, BNB, DOGE, XRP, TRX, LTC, and more).
• 🔗 Branded Hosted Checkouts: Automatic payment links with dynamic QR codes, live blockchain polling, and wallet deep linking.
• 🔔 Cryptographic Webhooks: HMAC-SHA256 signed Instant Payment Notifications (x-kkhay-signature).
• 🪶 Zero Dependencies: Pure Go standard library implementation (net/http, crypto/hmac, crypto/sha256, encoding/json).

---

📦 Installation

go get github.com/boboaungdev/kkhay-go@v1.0.4

(Requires Go 1.20 or newer)

---

🚀 Quickstart

1. Initialize the Client

Generate your API key in the K Khay Gateway Dashboard.

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/boboaungdev/kkhay-go"
)

func main() {
    client, err := kkhay.NewClient(os.Getenv("KKHAY_API_KEY")) // starts with "kkhay_live_"
    if err != nil {
        log.Fatalf("Failed to initialize client: %v", err)
    }

    ctx := context.Background()

    // 2. Create a crypto payment invoice
    resp, err := client.CreateInvoice(ctx, kkhay.CreateInvoiceRequest{
        Amount:        49.99,
        Currency:      "USD",
        PayNetwork:    "bsc",       // "bsc", "polygon", "base", "arbitrum", "ethereum", "solana", "bitcoin", "ton"
        PayToken:      "USDT",      // "USDT", "USDC", "BTC", "ETH", "SOL", "TON"
        OrderID:       "ORDER-9842",
        Title:         "Annual Pro Plan",
        CustomerName:  "Alice Smith",
        CustomerEmail: "alice@example.com",
        RedirectURL:   "https://myshop.com/orders/success",
        CancelURL:     "https://myshop.com/cart",
    })
    if err != nil {
        log.Fatalf("Failed to create invoice: %v", err)
    }

    fmt.Printf("Invoice ID: %s\n", resp.Invoice.ID)
    fmt.Printf("Gateway ID: %s\n", resp.Invoice.GatewayID)
    fmt.Printf("Deposit Address: %s\n", resp.Invoice.DepositAddress)
    fmt.Printf("Hosted Checkout URL: %s\n", resp.Invoice.HostedURL)
}

---

3. Query Invoice & Transaction Confirmations

inv, err := client.GetInvoice(ctx, "inv_0192a3b4c5d6")
if err != nil {
    log.Fatalf("Failed to get invoice: %v", err)
}

fmt.Printf("Status: %s\n", inv.Invoice.Status) // "WAITING" | "PAID" | "EXPIRED" | "CANCELED"

for _, p := range inv.Payments {
    fmt.Printf("Payment received: %s (Confirmations: %d, Status: %s)\n",
        p.AmountReceived, p.Confirmations, p.Status)
    fmt.Printf("Blockchain Tx: %s\n", p.TxHash)
}

---

4. List & Filter Invoices

res, err := client.ListInvoices(ctx, kkhay.ListInvoicesQuery{
    Page:   1,
    Limit:  20,
    Status: kkhay.StatusPaid,
})
if err != nil {
    log.Fatalf("Failed to list invoices: %v", err)
}

fmt.Printf("Total paid invoices: %d\n", res.TotalCount)
for _, item := range res.Items {
    fmt.Printf("- %s: %f %s (%s)\n", item.ID, item.Amount, item.Currency, item.Status)
}

---

5. Verify Incoming Webhooks (IPN)

When a customer pays and the blockchain confirms the transaction, K Khay sends a cryptographically signed POST webhook to your server with the x-kkhay-signature header.

package main

import (
    "io"
    "log"
    "net/http"
    "os"

    "github.com/boboaungdev/kkhay-go"
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPost {
        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
        return
    }

    body, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "Cannot read body", http.StatusBadRequest)
        return
    }
    defer r.Body.Close()

    signature := r.Header.Get("x-kkhay-signature")
    secret := os.Getenv("KKHAY_IPN_SECRET")

    event, err := kkhay.ParseWebhookEvent(body, signature, secret)
    if err != nil {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    if event.Event == kkhay.EventPaymentPaid || event.Event == kkhay.EventPaymentFinished {
        log.Printf("Payment confirmed for invoice %s (Gateway: %s)!", event.InvoiceID, event.GatewayID)
        log.Printf("Received: %s %s on %s", event.PayAmount, event.PayToken, event.PayNetwork)
        if event.TxHash != nil {
            log.Printf("Transaction Hash: %s", *event.TxHash)
        }
        // Fulfill your customer's order in your database
    }

    w.WriteHeader(http.StatusOK)
    w.Write([]byte(`{"ok": true}`))
}

func main() {
    http.HandleFunc("/webhooks/kkhay", webhookHandler)
    log.Println("Server listening on :8080...")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

---

🌐 Supported Networks & Families

Network Family	Popular Chains	Supported Tokens
EVM (180+ Chains)	Ethereum, BNB Smart Chain, Polygon, Arbitrum, Base, Optimism, Avalanche	USDT, USDC, ETH, BNB, POL, AVAX, DAI, and all ERC-20s
UTXO	Bitcoin, Dogecoin, Litecoin, Bitcoin Cash	BTC, DOGE, LTC, BCH
Solana	Solana Mainnet	SOL, USDT, USDC
TON	The Open Network	TON, USDT
Tron (TVM)	Tron Mainnet	TRX, USDT
XRPL	XRP Ledger	XRP

---

🛡️ Error Handling

The SDK returns structured *kkhay.APIError instances with HTTP status codes and error messages:

inv, err := client.GetInvoice(ctx, "inv_nonexistent")
if err != nil {
    if apiErr, ok := err.(*kkhay.APIError); ok {
        fmt.Printf("API Error HTTP %d [%s]: %s\n", apiErr.Status, apiErr.Code, apiErr.Message)
    } else {
        fmt.Printf("Unexpected error: %v\n", err)
    }
}

---

📄 License

MIT © K Khay

Documentation

Index

• Constants
• Variables
• func VerifyWebhookSignature(payload []byte, signature string, ipnSecret string) bool
• type APIError
  • func (e *APIError) Error() string
• type Client
  • func NewClient(apiKey string, opts ...ClientOption) (*Client, error)
  • func (c *Client) CheckHealth(ctx context.Context) (map[string]interface{}, error)
  • func (c *Client) CreateInvoice(ctx context.Context, req CreateInvoiceRequest) (*CreateInvoiceResponse, error)
  • func (c *Client) GetInvoice(ctx context.Context, invoiceID string) (*GetInvoiceResponse, error)
  • func (c *Client) ListInvoices(ctx context.Context, query ListInvoicesQuery) (*ListInvoicesResponse, error)
• type ClientOption
  • func WithBaseURL(url string) ClientOption
  • func WithHTTPClient(client *http.Client) ClientOption
  • func WithTimeout(timeout time.Duration) ClientOption
• type CreateInvoiceRequest
• type CreateInvoiceResponse
• type GetInvoiceResponse
• type Invoice
• type ListInvoicesQuery
• type ListInvoicesResponse
• type PaymentRecord
• type WebhookEvent
  • func ParseWebhookEvent(rawBody []byte, signature string, ipnSecret string) (*WebhookEvent, error)

Constants

const (
	StatusWaiting  = "WAITING"
	StatusPaid     = "PAID"
	StatusExpired  = "EXPIRED"
	StatusCanceled = "CANCELED"
)

Invoice status constants matching PostgreSQL GatewayInvoiceStatus enum.

const (
	TypePayment      = "PAYMENT"
	TypeDonation     = "DONATION"
	TypeSubscription = "SUBSCRIPTION"
)

Invoice type constants matching PostgreSQL GatewayInvoiceType enum.

const (
	SettlementModeNonCustodial = "NON_CUSTODIAL"
	SettlementModeCustodial    = "CUSTODIAL"
)

Settlement mode constants matching PostgreSQL GatewaySettlementMode enum.

const (
	PaymentMethodDeposit = "DEPOSIT"
	PaymentMethodWallet  = "WALLET"
)

Payment method constants matching PostgreSQL GatewayPaymentMethod enum.

const (
	PaymentStatusSettling = "SETTLING"
	PaymentStatusSettled  = "SETTLED"
	PaymentStatusFailed   = "FAILED"
)

Payment status constants matching PostgreSQL GatewayPaymentStatus enum.

const (
	EventPaymentPaid       = "payment.paid"
	EventPaymentFinished   = "payment.finished"
	EventPaymentConfirming = "payment.confirming"
	EventPaymentFailed     = "payment.failed"
	EventInvoiceCanceled   = "invoice.canceled"
)

Webhook event constants sent via Instant Payment Notifications (IPN).

const DefaultBaseURL = "https://api.kkhay.com"

DefaultBaseURL is the production API endpoint.

const Version = "1.0.4"

Version of the K Khay Go SDK.

Variables

var (
	// ErrInvalidSignature is returned when the webhook HMAC signature does not match.
	ErrInvalidSignature = errors.New("kkhay: invalid webhook signature")
)

Functions

func VerifyWebhookSignature

func VerifyWebhookSignature(payload []byte, signature string, ipnSecret string) bool

VerifyWebhookSignature verifies the HMAC-SHA256 signature sent with incoming IPN webhooks.

Types

type APIError

type APIError struct {
	Status  int         `json:"status"`
	Message string      `json:"message"`
	Code    string      `json:"code,omitempty"`
	Details interface{} `json:"details,omitempty"`
}

APIError represents an error response returned by the K Khay API.

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the official Go HTTP client for K Khay Payment Gateway.

func NewClient

func NewClient(apiKey string, opts ...ClientOption) (*Client, error)

NewClient constructs a new K Khay API client.

func (*Client) CheckHealth

func (c *Client) CheckHealth(ctx context.Context) (map[string]interface{}, error)

CheckHealth queries API health status.

func (*Client) CreateInvoice

func (c *Client) CreateInvoice(ctx context.Context, req CreateInvoiceRequest) (*CreateInvoiceResponse, error)

CreateInvoice creates a new sovereign crypto payment invoice.

func (*Client) GetInvoice

func (c *Client) GetInvoice(ctx context.Context, invoiceID string) (*GetInvoiceResponse, error)

GetInvoice retrieves an existing invoice by UUID.

func (*Client) ListInvoices

func (c *Client) ListInvoices(ctx context.Context, query ListInvoicesQuery) (*ListInvoicesResponse, error)

ListInvoices queries and paginates gateway invoices.

type ClientOption

type ClientOption func(*Client)

ClientOption configures a Client instance.

func WithBaseURL

func WithBaseURL(url string) ClientOption

WithBaseURL sets a custom base URL.

func WithHTTPClient

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient sets a custom http.Client.

func WithTimeout

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout sets a custom request timeout.

type CreateInvoiceRequest

type CreateInvoiceRequest struct {
	Amount          float64                `json:"amount,omitempty"`
	Currency        string                 `json:"currency,omitempty"`
	PriceAmount     float64                `json:"priceAmount,omitempty"`
	PriceCurrency   string                 `json:"priceCurrency,omitempty"`
	PayNetwork      string                 `json:"payNetwork"`
	PayToken        string                 `json:"payToken"`
	SettlementAsset string                 `json:"settlementAsset,omitempty"`
	Type            string                 `json:"type,omitempty"`
	OrderID         string                 `json:"orderId,omitempty"`
	Title           string                 `json:"title,omitempty"`
	CustomerName    string                 `json:"customerName,omitempty"`
	CustomerEmail   string                 `json:"customerEmail,omitempty"`
	RedirectURL     string                 `json:"redirectUrl,omitempty"`
	CancelURL       string                 `json:"cancelUrl,omitempty"`
	IPNCallbackURL  string                 `json:"ipnCallbackUrl,omitempty"`
	Metadata        map[string]interface{} `json:"metadata,omitempty"`
}

CreateInvoiceRequest parameters for generating a new crypto payment invoice.

type CreateInvoiceResponse

type CreateInvoiceResponse struct {
	OK      bool    `json:"ok"`
	Invoice Invoice `json:"invoice"`
}

CreateInvoiceResponse contains the created invoice and hosted checkout URL.

type GetInvoiceResponse

type GetInvoiceResponse struct {
	OK       bool            `json:"ok"`
	Invoice  Invoice         `json:"invoice"`
	Payments []PaymentRecord `json:"payments"`
}

GetInvoiceResponse contains the requested invoice and transaction records.

type Invoice

type Invoice struct {
	ID              string                 `json:"id"`
	GatewayID       string                 `json:"gatewayId"`
	Type            string                 `json:"type"`
	OrderID         *string                `json:"orderId"`
	Title           *string                `json:"title"`
	Amount          float64                `json:"amount"`
	Currency        string                 `json:"currency"`
	PriceAmount     float64                `json:"priceAmount"`
	PriceCurrency   string                 `json:"priceCurrency"`
	SettlementAsset *string                `json:"settlementAsset"`
	PayAmount       *string                `json:"payAmount"`
	PayToken        *string                `json:"payToken"`
	PayNetwork      *string                `json:"payNetwork"`
	LockedRate      *string                `json:"lockedRate"`
	DepositAddress  string                 `json:"depositAddress"`
	DerivationIndex *int                   `json:"derivationIndex,omitempty"`
	PayoutAddress   string                 `json:"payoutAddress"`
	Status          string                 `json:"status"`
	FeeAmount       string                 `json:"feeAmount"`
	NetAmount       string                 `json:"netAmount"`
	CustomerName    *string                `json:"customerName"`
	CustomerEmail   *string                `json:"customerEmail"`
	RedirectURL     *string                `json:"redirectUrl"`
	CancelURL       *string                `json:"cancelUrl"`
	IPNCallbackURL  *string                `json:"ipnCallbackUrl"`
	PaymentMethod   *string                `json:"paymentMethod"`
	SettlementMode  *string                `json:"settlementMode"`
	HostedURL       string                 `json:"hostedUrl"`
	Metadata        map[string]interface{} `json:"metadata"`
	ExpiresAt       string                 `json:"expiresAt"`
	CreatedAt       string                 `json:"createdAt"`
	UpdatedAt       string                 `json:"updatedAt"`
}

Invoice represents a K Khay sovereign payment invoice record.

type ListInvoicesQuery

type ListInvoicesQuery struct {
	Page   int    `json:"page,omitempty"`
	Limit  int    `json:"limit,omitempty"`
	Status string `json:"status,omitempty"`
	Type   string `json:"type,omitempty"`
	Search string `json:"search,omitempty"`
}

ListInvoicesQuery parameters for pagination and filtering.

type ListInvoicesResponse

type ListInvoicesResponse struct {
	OK          bool      `json:"ok"`
	Items       []Invoice `json:"items"`
	TotalCount  int       `json:"totalCount"`
	TotalPages  int       `json:"totalPages"`
	CurrentPage int       `json:"currentPage"`
	Limit       int       `json:"limit"`
}

ListInvoicesResponse paginated list of gateway invoices.

type PaymentRecord

type PaymentRecord struct {
	ID              string  `json:"id"`
	InvoiceID       string  `json:"invoiceId"`
	TxHash          string  `json:"txHash"`
	FromAddress     *string `json:"fromAddress"`
	AmountReceived  string  `json:"amountReceived"`
	Confirmations   int     `json:"confirmations"`
	Status          string  `json:"status"`
	ForwardedTxHash *string `json:"forwardedTxHash"`
	ForwardedAt     *string `json:"forwardedAt"`
	Token           *string `json:"token,omitempty"`
	Network         *string `json:"network,omitempty"`
	OrderID         *string `json:"orderId,omitempty"`
	Title           *string `json:"title,omitempty"`
	CreatedAt       string  `json:"createdAt"`
}

PaymentRecord details on-chain transaction hashes, confirmations, and settlement status.

type WebhookEvent

type WebhookEvent struct {
	Event          string  `json:"event"`
	InvoiceID      string  `json:"invoice_id"`
	GatewayID      string  `json:"gateway_id,omitempty"`
	InvoiceType    string  `json:"invoice_type,omitempty"`
	OrderID        *string `json:"order_id"`
	Amount         float64 `json:"amount,omitempty"`
	Currency       string  `json:"currency,omitempty"`
	PriceAmount    float64 `json:"price_amount"`
	PriceCurrency  string  `json:"price_currency"`
	PayAmount      string  `json:"pay_amount"`
	PayToken       string  `json:"pay_token"`
	PayNetwork     string  `json:"pay_network"`
	DepositAddress string  `json:"deposit_address"`
	TxHash         *string `json:"tx_hash"`
	Status         string  `json:"status"`
	Timestamp      string  `json:"timestamp"`
}

WebhookEvent payload sent via IPN.

func ParseWebhookEvent

func ParseWebhookEvent(rawBody []byte, signature string, ipnSecret string) (*WebhookEvent, error)

ParseWebhookEvent validates signature and parses the raw JSON body into WebhookEvent.