Skip to Content
SDKsNexus SDK (Cloud Integration)Go

Go SDK

GitHub Repository: sunbay-nexus-sdk-go 

Official SUNBAY Nexus Go SDK, providing complete payment integration capabilities for Go applications.

Features

  • ✅ Clean Go-style API
  • ✅ Complete type definitions
  • ✅ Automatic authentication
  • ✅ Automatic retry for GET requests
  • ✅ Comprehensive error handling
  • ✅ HTTP connection pool management
  • ✅ Support for custom logging
  • ✅ Context support
  • ✅ Zero external dependencies (standard library only)

Installation

go get github.com/sunbay-developer/sunbay-nexus-sdk-go

Quick Start

1. Initialize Client

NexusClient is goroutine-safe and should be created once and reused globally. Do not create a new client for every request — each instance manages its own HTTP connection pool, and repeated creation wastes resources.

package main
 
import (
    "context"
    "fmt"
    "log"
 
    nexus "github.com/sunbay-developer/sunbay-nexus-sdk-go"
    "github.com/sunbay-developer/sunbay-nexus-sdk-go/errors"
    "github.com/sunbay-developer/sunbay-nexus-sdk-go/model/request"
    "github.com/sunbay-developer/sunbay-nexus-sdk-go/model/common"
)
 
func main() {
    config := &nexus.Config{
        APIKey:  "your-api-key",
        BaseURL: "https://open.sunbay.us",
    }
    client, err := nexus.NewNexusClient(config)
    if err != nil {
        log.Fatal(err)
    }
 
    // Use client throughout the application...
}

We recommend tuning ConnectTimeout, ReadTimeout, MaxRetries, MaxTotal, and MaxPerRoute based on your concurrency level and business requirements. See Configuration Options for details.

2. Create Payment Transaction

Important: All amount fields use the smallest currency unit (cents). For example: 100.00 USD = 10000 cents. Amount fields use *int64 pointers.

orderAmount := int64(10000)
req := &request.SaleRequest{
    AppID:                "app_123456",
    MerchantID:           "mch_789012",
    ReferenceOrderID:     "ORDER20231119001",
    TransactionRequestID: "PAY_REQ_1234567890",
    Amount: &common.SaleAmount{
        OrderAmount:   &orderAmount,
        PriceCurrency: "USD",
    },
    Description: "Product purchase",
    TerminalSN:  "T1234567890",
}
 
ctx := context.Background()
resp, err := client.Sale(ctx, req)
if err != nil {
    if bizErr, ok := err.(*errors.BusinessError); ok {
        log.Printf("Business error: code=%s, msg=%s, traceID=%s",
            bizErr.Code(), bizErr.Message(), bizErr.TraceID())
    } else if netErr, ok := err.(*errors.NetworkError); ok {
        log.Printf("Network error: %v (retryable: %v)", netErr, netErr.IsRetryable())
    }
    return
}
 
fmt.Printf("Transaction ID: %s\n", resp.TransactionID)

API Methods

All methods take context.Context as the first parameter and return (*Response, error).

In-Person Payment APIs

  • Sale(ctx, req) - Payment transaction
  • Auth(ctx, req) - Pre-authorization
  • ForcedAuth(ctx, req) - Forced authorization
  • IncrementalAuth(ctx, req) - Incremental authorization
  • PostAuth(ctx, req) - Post-authorization completion
  • Refund(ctx, req) - Refund
  • Void(ctx, req) - Void transaction
  • Abort(ctx, req) - Abort transaction
  • TipAdjust(ctx, req) - Tip adjustment
  • BatchQuery(ctx, req) - Query open (unsettled) batches
  • BatchClose(ctx, req) - Batch settlement
  • BatchCloseList(ctx, req) - Query closed (settled) batches

Online Payment APIs

  • CreateCheckoutSession(ctx, req) - Create hosted checkout session
  • ExpireCheckoutSession(ctx, req) - Expire a checkout session
  • DirectPayment(ctx, req) - Direct payment (server-to-server)
  • OnlineRefund(ctx, req) - Online refund

Transaction Query APIs

  • Query(ctx, req) - Query transaction

Merchant APIs

  • MerchantQuery(ctx, req) - Retrieve merchant information
  • MerchantTerminalsQuery(ctx, req) - List terminals bound to a merchant

Error Handling

The SDK returns two types of errors:

  • *errors.BusinessError: Business logic errors (parameter validation, API business errors, etc.)
  • *errors.NetworkError: Network-related errors (connection timeout, network errors, etc.)
resp, err := client.Sale(ctx, req)
if err != nil {
    if bizErr, ok := err.(*errors.BusinessError); ok {
        log.Printf("Business error: code=%s, msg=%s, traceID=%s",
            bizErr.Code(), bizErr.Message(), bizErr.TraceID())
    } else if netErr, ok := err.(*errors.NetworkError); ok {
        log.Printf("Network error: %v (retryable: %v)", netErr, netErr.IsRetryable())
        // NetworkError supports Go 1.13 error wrapping via Unwrap()
    }
    return
}

Enum Types

The SDK provides typed string enums in the model/types package, each with String() and IsValid() methods:

  • TransactionStatus - I (Initial), P (Processing), S (Success), F (Fail), C (Closed)
  • TransactionType - SALE, AUTH, FORCED_AUTH, INCREMENTAL, POST_AUTH, REFUND, VOID
  • CardNetworkType - CREDIT, DEBIT, EBT, EGC, UNKNOWN
  • EntryMode - MANUAL, SWIPE, FALLBACK_SWIPE, CONTACT, CONTACTLESS
  • AuthenticationMethod - NOT_AUTHENTICATED, PIN, OFFLINE_PIN, BY_PASS, SIGNATURE
  • PaymentCategory - CARD, CARD-CREDIT, CARD-DEBIT, QR-MPM, QR-CPM
  • PrintReceipt - NONE, MERCHANT, CUSTOMER, BOTH
  • BatchClosePrintReceipt - TOTAL, DETAIL, BOTH, NONE, AUTO
  • RelatedTransactionStatus - VOIDED, INCREMENTAL, REFUNDED, CAPTURE, PART_REFUNDED
  • TransactionBatchStatus - N, U, C
  • EBTSubID - SNAP, VOUCHER, BENEFIT

Configuration Options

import "time"
 
config := &nexus.Config{
    APIKey:         "your-api-key",                   // Required
    BaseURL:        "https://open.sunbay.us",         // Default: https://open.sunbay.us
    ConnectTimeout: 10 * time.Second,                 // Default: 10 seconds
    ReadTimeout:    30 * time.Second,                 // Default: 30 seconds
    MaxRetries:     3,                                // Default: 3 times (GET request retry)
    MaxTotal:       200,                              // Default: 200 (max connections in pool)
    MaxPerRoute:    200,                              // Default: 200 (max connections per route)
    Logger:         customLogger,                     // Default: console logger
}

Logging

The SDK accepts any implementation of the Logger interface:

type Logger interface {
    Debug(args ...interface{})
    Debugf(format string, args ...interface{})
    Info(args ...interface{})
    Infof(format string, args ...interface{})
    Warn(args ...interface{})
    Warnf(format string, args ...interface{})
    Error(args ...interface{})
    Errorf(format string, args ...interface{})
}

If no logger is provided, a default console logger is used.

Complete Example

package main
 
import (
    "context"
    "fmt"
    "log"
    "time"
 
    nexus "github.com/sunbay-developer/sunbay-nexus-sdk-go"
    "github.com/sunbay-developer/sunbay-nexus-sdk-go/errors"
    "github.com/sunbay-developer/sunbay-nexus-sdk-go/model/request"
    "github.com/sunbay-developer/sunbay-nexus-sdk-go/model/common"
)
 
func main() {
    config := &nexus.Config{
        APIKey:  "your-api-key",
        BaseURL: "https://open.sunbay.us",
    }
 
    client, err := nexus.NewNexusClient(config)
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }
 
    orderAmount := int64(10000)
    req := &request.SaleRequest{
        AppID:                "app_123456",
        MerchantID:           "mch_789012",
        ReferenceOrderID:     "ORDER20231119001",
        TransactionRequestID: fmt.Sprintf("PAY_REQ_%d", time.Now().Unix()),
        Amount: &common.SaleAmount{
            OrderAmount:   &orderAmount,
            PriceCurrency: "USD",
        },
        Description: "Product purchase",
        TerminalSN:  "T1234567890",
    }
 
    ctx := context.Background()
    resp, err := client.Sale(ctx, req)
    if err != nil {
        if bizErr, ok := err.(*errors.BusinessError); ok {
            log.Printf("Business error: %s - %s (TraceID: %s)",
                bizErr.Code(), bizErr.Message(), bizErr.TraceID())
        } else if netErr, ok := err.(*errors.NetworkError); ok {
            log.Printf("Network error: %v (Retryable: %v)", netErr, netErr.IsRetryable())
        }
        return
    }
 
    fmt.Printf("Transaction successful!\n")
    fmt.Printf("Transaction ID: %s\n", resp.TransactionID)
}

System Requirements

  • Go 1.18 or higher
  • No external dependencies (standard library only)

License

MIT License

Last updated on
Node.js.NET (C#)