kkhay

README

K Khay Go SDK 🚀

Official Go SDK for the K Khay Sovereign Crypto Payment Gateway.

Accept non-custodial and custodial crypto payments (USDT, USDC, BNB, ETH on BSC, Polygon, Arbitrum, Base, Ethereum) with zero external dependencies using the Go standard library.

---

📦 Installation

go get github.com/boboaungdev/kkhay-go

(Requires Go 1.20 or newer)

---

⚡ Quick Start

1. Initialize Client

package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    client, err := kkhay.NewClient("kkhay_live_your_api_key_here")
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Create an invoice
    resp, err := client.CreateInvoice(ctx, kkhay.CreateInvoiceRequest{
        PriceAmount:   49.99,
        PriceCurrency: "USD",
        PayNetwork:    "bsc",
        PayToken:      "USDT",
        OrderID:       "ORD-8821",
        Title:         "Pro Tier Subscription",
        RedirectURL:   "https://myshop.com/success",
    })
    if err != nil {
        log.Fatalf("Invoice error: %v", err)
    }

    fmt.Printf("Invoice ID: %s\n", resp.Invoice.ID)
    fmt.Printf("Checkout URL: %s\n", resp.Invoice.HostedURL)
}

2. Query Invoice & Transaction Confirmations

inv, err := client.GetInvoice(ctx, "inv_9f81a7b2")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Status: %s\n", inv.Invoice.Status)
for _, p := range inv.Payments {
    fmt.Printf("Received %s on tx %s (confirms: %d)\n", p.AmountReceived, p.TxHash, p.Confirmations)
}

---

🔐 Webhook / IPN Verification (net/http)

package main

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

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

func handleKkhayWebhook(w http.ResponseWriter, r *http.Request) {
    body, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "Bad request", http.StatusBadRequest)
        return
    }

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

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

    if event.Event == "payment.finished" {
        log.Printf("Order %s was paid! Tx: %v", *event.OrderID, event.TxHash)
    }

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

---

📄 License

MIT © K Khay

Documentation

Index

• 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)

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 merchant 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 {
	PriceAmount    float64                `json:"priceAmount"`
	PriceCurrency  string                 `json:"priceCurrency,omitempty"`
	PayNetwork     string                 `json:"payNetwork"`
	PayToken       string                 `json:"payToken"`
	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 invoice.

type CreateInvoiceResponse

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

CreateInvoiceResponse contains the created invoice and status.

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"`
	MerchantID     string  `json:"merchantId"`
	OrderID        *string `json:"orderId"`
	Title          *string `json:"title"`
	PriceAmount    float64 `json:"priceAmount"`
	PriceCurrency  string  `json:"priceCurrency"`
	PayAmount      string  `json:"payAmount"`
	PayToken       string  `json:"payToken"`
	PayNetwork     string  `json:"payNetwork"`
	DepositAddress string  `json:"depositAddress"`
	Status         string  `json:"status"`
	FeeAmount      string  `json:"feeAmount"`
	NetAmount      string  `json:"netAmount"`
	SettlementMode *string `json:"settlementMode"`
	PaymentMethod  *string `json:"paymentMethod"`
	HostedURL      string  `json:"hostedUrl"`
	RedirectURL    *string `json:"redirectUrl"`
	CancelURL      *string `json:"cancelUrl"`
	ExpiresAt      string  `json:"expiresAt"`
	CreatedAt      string  `json:"createdAt"`
}

Invoice represents a K Khay invoice record.

type ListInvoicesQuery

type ListInvoicesQuery struct {
	Page   int    `json:"page,omitempty"`
	Limit  int    `json:"limit,omitempty"`
	Status string `json:"status,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 merchant invoices.

type PaymentRecord

type PaymentRecord struct {
	ID              string  `json:"id"`
	TxHash          string  `json:"txHash"`
	AmountReceived  string  `json:"amountReceived"`
	Confirmations   int     `json:"confirmations"`
	Status          string  `json:"status"`
	ForwardedTxHash *string `json:"forwardedTxHash"`
	CreatedAt       string  `json:"createdAt"`
}

PaymentRecord details on-chain transaction hashes and confirmations.

type WebhookEvent

type WebhookEvent struct {
	Event          string  `json:"event"`
	InvoiceID      string  `json:"invoice_id"`
	OrderID        *string `json:"order_id"`
	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.