Latest release: 1.5.1
go get github.com/alipay/global-open-sdk-go@latestRequires Go 1.22.5+. Use a supported Go release with current security fixes.
- 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.
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_keyThe 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.
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 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.
}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.
Billing integrations: availableAmount now uses Amount; the AvailableAmount
model has been removed.
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.
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
}For integration questions, contact overseas_support@service.alibaba.com.