Go SDK

The UQPAY Go SDK provides typed access to Account Center, Global Account, Global Acquiring, Card Issuance, and Supporting Services. It includes automatic Access Token management, automatic idempotency keys, request options, webhook verification, PGP authorization decisions, and sandbox transaction simulation.

GitHub

github.com/uqpay/uqpay-sdk-go/v2

The SDK requires Go 1.19 or later. v2.1.0 is the current stable release. Version v1.2.0 is its first release in the coordinated client release line.

Installation

go get github.com/uqpay/uqpay-sdk-go/v2@v2.1.0
go mod tidy

Quick start

Before you begin, create a sandbox account and create API keys.

package main

import (
    "context"
    "log"

    "github.com/uqpay/uqpay-sdk-go/v2"
    "github.com/uqpay/uqpay-sdk-go/v2/configuration"
    "github.com/uqpay/uqpay-sdk-go/v2/issuing"
)

func main() {
    client, err := uqpay.NewClient(
        "your-client-id",
        "your-api-key",
        configuration.Sandbox(),
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Create a cardholder
    cardholder, err := client.Issuing.Cardholders.Create(ctx, &issuing.CreateCardholderRequest{
        Email:       "user@example.com",
        PhoneNumber: "1234567890",
        FirstName:   "John",
        LastName:    "Doe",
        CountryCode: "US",
    })
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Cardholder ID: %s\n", cardholder.CardholderID)
}

Configuration

Direct parameters
Environment variables
Custom endpoint

Sandbox:

client, err := uqpay.NewClient(clientID, apiKey, configuration.Sandbox())

Production:

client, err := uqpay.NewClient(clientID, apiKey, configuration.Production())

export UQPAY_CLIENT_ID="your-client-id"
export UQPAY_API_KEY="your-api-key"

Read the variables explicitly when you create the client. The SDK does not load environment variables or .env files automatically.

clientID := os.Getenv("UQPAY_CLIENT_ID")
apiKey := os.Getenv("UQPAY_API_KEY")
client, err := uqpay.NewClient(clientID, apiKey, configuration.Sandbox())

client, err := uqpay.NewClient(clientID, apiKey, &configuration.Config{
    BaseURL: "https://custom-api.example.com/api",
})

Authentication

The SDK manages UQPAY Access Tokens automatically:

Retrieves an Access Token using clientID and apiKey
Caches the Token until it nears expiry
Retrieves a new Token before the current one expires
Provides concurrency-safe Token management

Idempotency

Every API request automatically includes a unique idempotency key to ensure safe retries and prevent duplicate operations. You do not need to set this manually.

Error handling

The SDK returns detailed error information including HTTP status codes and API error details:

card, err := client.Issuing.Cards.Get(ctx, cardID)
if err != nil {
    log.Printf("Error: %v\n", err)
    return
}

Example error format:

failed to get card: 404: card_not_found: Card not found (HTTP 404)

Authorization decision (PGP)

Authorization decisions let your endpoint approve or decline card transactions in real time. UQPAY sends a PGP-encrypted transaction to your endpoint; the SDK decrypts it, calls your decision function, and encrypts the response. Before implementing the handler, review the authorization decision workflow, enablement requirements, response codes, and timeout window. Generate an RSA-2048 key pair, exchange the public key with UQPAY, and keep the private key secure:

keys, err := authdecision.GenerateKeyPair("Acme Corp", "issuing@acme.example")
if err != nil {
    log.Fatal(err)
}

Configure the keys and register the HTTP handler:

err := client.Issuing.AuthDecision.Configure(authdecision.Config{
    PrivateKey:     os.Getenv("AUTH_DECISION_PRIVATE_KEY"),
    UQPayPublicKey: os.Getenv("UQPAY_PGP_PUBLIC_KEY"),
    Passphrase:     os.Getenv("PGP_PASSPHRASE"),
})
if err != nil {
    log.Fatal(err)
}

handler, err := client.Issuing.AuthDecision.Handler(authdecision.HandlerOptions{
    DecisionTimeout: 1500 * time.Millisecond,
    Decide: func(ctx context.Context, tx authdecision.Transaction) (authdecision.Result, error) {
        return authdecision.Result{
            ResponseCode:       "00",
            PartnerReferenceID: "ref-001",
        }, nil
    },
})
if err != nil {
    log.Fatal(err)
}

http.Handle("/auth-decision", handler)

The SDK preserves monetary values as strings, accepts amounts encoded as JSON strings or numbers, and aborts the HTTP response on processing errors so UQPAY can apply the configured timeout action.

API coverage

Namespace	Product	Main resources
`client.Connect`	Account Center	Accounts and RFIs
`client.Banking`	Global Account	Balances, transfers, deposits, beneficiaries, payouts, virtual accounts, conversions, and exchange rates
`client.Payment`	Global Acquiring	Payment intents, attempts, refunds, settlements, balances, payouts, bank accounts, and terminals
`client.Issuing`	Card Issuance	Cardholders, cards, transactions, products, balances, transfers, reports, merchant controls, download center, and authorization decisions
`client.Supporting`	Supporting Services	File upload and download links
`client.Simulator`	Sandbox	Deposits, card authorizations, and reversals

Stablecoin Account (Ramp) is not included in the current SDK product scope.

Resources

Use each product namespace.

Webhooks

Verify incoming webhook signatures.

Authorization decisions

Process PGP-encrypted card authorization requests.

MCP

CLI

SDKs

GitHub

Installation

Quick start

Configuration

Authentication

Idempotency

Error handling

Authorization decision (PGP)

API coverage

Resources

Webhooks

Authorization decisions

GitHub

​Installation

​Quick start

​Configuration

​Authentication

​Idempotency

​Error handling

​Authorization decision (PGP)

​API coverage

Resources

Webhooks

Authorization decisions

Installation

Quick start

Configuration

Authentication

Idempotency

Error handling

Authorization decision (PGP)

API coverage