smartwalle/alipay Go SDK

If the SDK does not have a built-in method for a specific Alipay interface, you can use alipay.NewPayload combined with alipay.Client methods to perform the request.

Depending on your goal, use one of the following three methods:

1. Request(payload, &result): To make a network request to Alipay (e.g., for querying transaction status).
2. BuildURL(payload): To generate a URL for web-based payments (e.g., alipay.trade.page.pay).
3. EncodeParam(payload): To generate signed parameters (e.g., for App payments like alipay.trade.app.pay).

If you use the Public Certificate mode for signature verification, you must load the certificates downloaded from your Alipay application.

Note: You cannot use Public Certificate mode and Ordinary Public Key mode simultaneously; you must choose one.

To use the recommended v3 version of the SDK with Go modules, run the following command:

go get github.com/smartwalle/alipay/v3

Then import it in your Go code:

import "github.com/smartwalle/alipay/v3"

If you are not using Go modules, use:

go get github.com/smartwalle/alipay

and import github.com/smartwalle/alipay.

When Alipay's server calls your NotifyURL, use DecodeNotification to parse the message and verify the signature automatically.

After successfully processing the notification, you must call alipay.ACKNotification(writer) to acknowledge receipt; otherwise, Alipay will continue to send the same notification.

Alipay provides a sandbox environment for development and testing, which includes independent merchant and buyer accounts.

There are two gateway addresses:

• New address (Default): https://openapi-sandbox.dl.alipaydev.com/gateway.do
• Old address: https://openapi.alipaydev.com/gateway.do

By default, the SDK uses the new address. If your integration requires the old address, specify it during initialization using alipay.WithPastSandboxGateway().

alipay.New(appId, privateKey, isProduction, alipay.WithPastSandboxGateway())

The SDK uses RSA2 for signing. When generating keys using the Alipay RSA signing tool, a key length of 2048 is recommended. Ensure you configure RSA2(SHA256) keys in the Alipay management console.

To use the Certificate Mode (Public Key Certificate mode), you must load the following files into the client:

1. App Certificate Public Key: Your application's public certificate.
2. Alipay Root Certificate: The root certificate from Alipay.
3. Alipay Certificate Public Key: The public key certificate from Alipay.

You can also optionally set an encryption key for interface content encryption using SetEncryptKey.

When a user is redirected back to your ReturnURL after a web payment, use VerifySign to validate the parameters provided by Alipay.

Important: It is recommended that your ReturnURL does not contain any extra query parameters, as VerifySign validates all received parameters. If you must use parameters, remove them from request.Form before calling VerifySign.

When querying a transaction, the TradeStatus field in the response indicates the current state of the order. Use the TradeStatus type to handle these constants:

• WAIT_BUYER_PAY: Transaction created, awaiting buyer payment.
• TRADE_SUCCESS: Payment successful.
• TRADE_CLOSED: Transaction closed due to timeout or full refund.
• TRADE_FINISHED: Transaction finished and cannot be refunded.

// Possible values for TradeStatus
const (
	TradeStatusWaitBuyerPay TradeStatus = "WAIT_BUYER_PAY"
	TradeStatusClosed       TradeStatus = "TRADE_CLOSED"
	TradeStatusSuccess      TradeStatus = "TRADE_SUCCESS"
	TradeStatusFinished     TradeStatus = "TRADE_FINISHED"
)

The New and NewWithSigner functions accept functional options to customize the client behavior:

• WithTimeLocation(location *time.Location): Sets the time location for timestamp generation.
• WithHTTPClient(client *http.Client): Provides a custom HTTP client.
• WithVerifier(aliCertSN string, verifier Verifier): Registers a custom verifier for a specific Alipay certificate serial number (useful if certificates are managed externally).
• WithSandboxGateway(gateway string): Sets a custom gateway for sandbox mode.
• WithProductionGateway(gateway string): Sets a custom gateway for production mode.
• WithNewSandboxGateway(): Explicitly sets the new sandbox gateway.
• WithPastSandboxGateway(): Sets the legacy sandbox gateway.

To start using the SDK, use New to create a client. You must provide your appId, your application's privateKey, and a boolean indicating if you are in production mode. If production is false, the client defaults to the sandbox environment.

You can also use NewWithSigner if your private key is managed by a third party and you need to provide a custom nsign.Signer implementation.