Antom SDK for Go

Latest release: 1.5.2

Installation

go get github.com/alipay/global-open-sdk-go@latest

Requires Go 1.22.5+. Use a supported Go release with current security fixes.

Quick start

• RSA: follow the configuration and inline example below.
• API Key (limited availability): follow the setup guide and run the sandbox example.
• Browse more examples and the API documentation.

RSA and API Key clients share request/response models. File uploads and notification verification still require RSA credentials.

RSA configuration

Before using the RSA client, prepare these values from your Antom integration:

gatewayUrl=your_regional_https_gateway
clientId=your_client_id
merchantPrivateKey=your_merchant_private_key
alipayPublicKey=your_antom_public_key

The examples read them from ANTOM_GATEWAY_URL, ANTOM_CLIENT_ID, ANTOM_MERCHANT_PRIVATE_KEY, and ANTOM_PUBLIC_KEY, respectively. Keep keys in server-side configuration. Replace sample order data and callback URLs with your own values before sending a request.

Payment

Save as main.go in your application module. Run go mod tidy to resolve the example’s imports, configure the four environment variables above, then use go run ..

package main

import (
    "fmt"
    "os"
    antom "github.com/alipay/global-open-sdk-go/com/alipay/api"
    "github.com/alipay/global-open-sdk-go/com/alipay/api/model"
    "github.com/alipay/global-open-sdk-go/com/alipay/api/request/pay"
    responsePay "github.com/alipay/global-open-sdk-go/com/alipay/api/response/pay"
    "github.com/google/uuid"
)

func main() {
    client := antom.NewDefaultAlipayClient(
        os.Getenv("ANTOM_GATEWAY_URL"), os.Getenv("ANTOM_CLIENT_ID"),
        os.Getenv("ANTOM_MERCHANT_PRIVATE_KEY"), os.Getenv("ANTOM_PUBLIC_KEY"))
    payRequest, request := pay.NewAlipayPayRequest()

    request.PaymentRequestId = uuid.NewString()
    order := &model.Order{}
    order.OrderDescription = "example order"
    order.ReferenceOrderId = "28947397358748"
    order.OrderAmount = model.NewAmount("100", "HKD")
    merchant := &model.Merchant{}
    merchant.ReferenceMerchantId = "1238rye8yr8erwer"
    merchant.MerchantMCC = "7011"
    merchant.MerchantName = "example merchant"
    merchant.Store = &model.Store{StoreMCC: "7011", ReferenceStoreId: "289285674", StoreName: "store 1111"}
    order.Merchant = merchant
    order.Env = &model.Env{OsType: model.ANDROID, TerminalType: model.WEB}
    request.Order = order

    request.PaymentAmount = model.NewAmount("100", "HKD")

    request.PaymentNotifyUrl = "https://www.yourNotifyUrl.com"
    request.PaymentRedirectUrl = "https://www.yourRedirectUrl.com"

    request.PaymentMethod = &model.PaymentMethod{PaymentMethodType: model.ALIPAY_HK, PaymentMethodId: "1234567890"}

    request.ProductCode = model.CASHIER_PAYMENT

    execute, err := client.Execute(payRequest)
    if err != nil {
    print(err.Error())
    return
    }
    response := execute.(*responsePay.AlipayPayResponse)
    fmt.Println(response.Result)
}

API Key client (limited availability)

API Key access is not yet available to all merchants. Use this client only if API Key access has been enabled for your account; otherwise, use RSA.

Set ANTOM_GATEWAY_URL and ANTOM_API_KEY in your server environment. This initializes the client; see the setup guide for a complete sandbox request and its additional configuration.

package main

import (
    "os"
    antom "github.com/alipay/global-open-sdk-go/com/alipay/api"
)

func main() {
    client, err := antom.NewApiKeyAlipayClient(
        os.Getenv("ANTOM_GATEWAY_URL"), os.Getenv("ANTOM_API_KEY"))
    if err != nil { panic(err) }
    defer client.Close()
    // Use client.Execute(request) with a business request.
}

Exact amount conversion

Available in SDK version 1.5.0 and later.

Convert a decimal amount string into Antom’s integer-string Amount.value, convert it back to a fixed-precision decimal string, or validate an outbound value. Conversion returns a string, not an Amount object, and uses bundled currency rules without a network request.

This example checks the error returned by each operation:

package main

import (
    "fmt"
    "log"

    "github.com/alipay/global-open-sdk-go/com/alipay/api/tools"
)

func main() {
    value, err := tools.ToAmount("10.25", "USD")
    if err != nil {
        log.Fatal(err)
    }
    amount, err := tools.FromAmount(value, "USD")
    if err != nil {
        log.Fatal(err)
    }
    if err := tools.Validate(value, "USD"); err != nil {
        log.Fatal(err)
    }
    fmt.Println(value, amount) // 1025 10.25
}

Validate returns nil on success. Invalid input or bundled-rule loading failures return a non-nil error. Error messages include categories such as UNSUPPORTED_CURRENCY, EXCESS_PRECISION, VALUE_TOO_LONG, and RULE_VIOLATION.

• Pass amounts, values, and currency codes as strings. Use uppercase currency codes and unsigned ASCII numbers, without spaces, separators, or exponents.
• Supported currencies: AUD, BDT, BRL, CAD, CLP, CNY, EUR, GBP, HKD, IDR, JPY, KRW, MXN, MYR, NZD, PEN, PHP, PKR, PLN, SGD, THB, TWD, USD, VND. Other codes are rejected; there is no default conversion multiplier.
• Conversion is exact and never rounds. Extra non-zero decimal places are rejected; trailing zero decimal places are allowed. Zero is accepted, but callers must check whether the target API permits a zero amount.
• The 16-digit limit applies to Amount.value, not to the decimal input string or the business transaction limit. Conversion to a value checks the normalized result; conversion from a value and validation count all input digits, including leading zeros.
• For IDR, conversion to a value and outbound validation require the value to be a multiple of 100. Conversion from a value does not apply this outbound restriction and never rounds the response amount.

See Antom’s amount rules for the conversion convention. Supported payment-method currencies, transaction limits, and method-specific constraints (such as JKOPay TWD or Octopus HKD multiples) must be checked separately; this utility does not validate payment-method context.

Upgrade notes

Billing integrations: availableAmount now uses Amount; the AvailableAmount model has been removed.

Meter event upload

meter/createSession uses the regular signed AMS transport. Call meter/uploadEvent with ExecuteWithHeaders and the returned X-Session-Id. The SDK uses the gateway URL configured on the client without sandbox path rewriting, request signing, response signature verification, or automatic retries. This API requires HTTP/2 and supports the Go version declared in go.mod. For production use, build applications with a currently supported Go release containing the latest security fixes.

See the Meter example for a complete request.

Advanced usage

DefaultAlipayClient.Execute handles JSON serialization, signing, HTTP calls, and response verification. The following is an implementation excerpt from the client source, not a standalone application example: private helpers are defined in the SDK package.

type DefaultAlipayClient struct {
    GatewayUrl         string
    ClientId           string
    MerchantPrivateKey string
    AlipayPublicKey    string
    AgentToken         string
    IsSandboxMode      bool
    uploadGatewayUrl   string
}

func NewDefaultAlipayClient(gatewayUrl, clientId, merchantPrivateKey, alipayPublicKey string, agentTokenOpt ...string) *DefaultAlipayClient {
    isSandboxMode := strings.HasPrefix(clientId, "SANDBOX_")

    c := &DefaultAlipayClient{
        GatewayUrl:         gatewayUrl,
        ClientId:           clientId,
        MerchantPrivateKey: merchantPrivateKey,
        AlipayPublicKey:    alipayPublicKey,
        IsSandboxMode:      isSandboxMode,
    }
    if len(agentTokenOpt) > 0 {
        c.AgentToken = agentTokenOpt[0]
    }
    return c
}

func (alipayClient *DefaultAlipayClient) Execute(alipayRequest *request.AlipayRequest) (any, error) {
    reqPayload, err := json.Marshal(alipayRequest.Param)
    if err != nil {
        return nil, &exception.AlipayLibraryError{Message: "json.Marshal is fail " + err.Error()}
    }
    AdjustSandboxUrl(alipayClient.IsSandboxMode, alipayRequest)
    path := alipayRequest.Path
    httpMethod := alipayRequest.HttpMethod
    reqTime := strconv.FormatInt(time.Now().UnixMilli(), 10)
    sign, err := tools.GenSign(fmt.Sprintf("%s", httpMethod), path, alipayClient.ClientId, reqTime, string(reqPayload), alipayClient.MerchantPrivateKey)
    if err != nil {
        return nil, err
    }
    header := buildBaseHeader(reqTime, alipayClient.ClientId, alipayRequest.KeyVersion, sign, alipayClient.AgentToken)
    alipayResponse, err := alipayClient.httpDo(alipayClient.GatewayUrl+path, httpMethod, map[string]string{}, header, reqPayload, alipayRequest.AlipayResponse)
    if err != nil {
        return nil, err
    }
    return alipayResponse, nil
}

Support

For integration questions, contact overseas_support@service.alibaba.com.