Omise Go Client Library

Install the Omise Go library using go get:

go get github.com/omise/omise-go

To handle incoming Omise webhook events, you must implement the EventHandler interface or provide an EventHandlerFunc. The handler receives the http.ResponseWriter, the original *http.Request, and a pre-unmarshaled *Event object containing the webhook data.

You can implement this by creating a struct that satisfies the HandleEvent method, or more simply, by defining a function with the signature func(http.ResponseWriter, *http.Request, *Event) and casting it to EventHandlerFunc.

// Using EventHandlerFunc for a simple implementation
myHandler := omise.EventHandlerFunc(func(w http.ResponseWriter, r *http.Request, event *omise.Event) {
    fmt.Printf("Received event: %s\n", event.EventType)
    w.WriteHeader(http.StatusOK)
})

To monitor the response code and body from every API call, call SetDebug(true) on your client instance immediately after initialization.

client, e := omise.NewClient(OmisePublicKey, OmiseSecretKey)
if e != nil {
	log.Fatal(e)
}

// Enabling debug mode to monitor response from API call
client.SetDebug(true)

You can specify a specific Omise API version on the client instance. This setting takes priority over the version configured in your Omise Dashboard, which is useful for managing different environments (e.g., using a newer version in development and an older version in production).

client.APIVersion = "2015-11-06"

The Client struct exposes an Endpoints field, which is a map[internal.Endpoint]string. You can use this to override the default URL for specific API endpoints. This is useful for pointing the client to a mock server or a different environment.

client.Endpoints[someEndpointKey] = "https://custom-api.example.com"

Use NewClient(pkey, skey string) to create a new Client instance. You must provide your Omise public key (pkey) and secret key (skey). These keys can be obtained from the Omise Dashboard.

The Client manages HTTP operations against the Omise REST API and should be used in conjunction with operation structures from the operations subpackage.

import "github.com/omise/omise-go"

client, err := omise.NewClient("pkey_test_...", "skey_test_...")
if err != nil {
    // handle error
}

In multi-tenant scenarios where you need to use different credentials for different requests while reusing the same underlying http.Client, use DoWithKeys(result interface{}, pkey, skey string, operation internal.Operation).

Concurrency Warning: DoWithKeys is safe to call from multiple goroutines sharing the same Client instance. However, you must treat the Client configuration (context, custom headers, user agent, and endpoint settings) as immutable once the client is shared. Do not call configuration methods like WithCustomHeaders or WithContext while the client is being used concurrently, as this causes data races.

var result MyResponseStruct
// Use specific keys for this request without changing the client's global state
err := client.DoWithKeys(&result, "pkey_tenant_a", "skey_tenant_a", operation)

When an API call fails, the library may return an *Error struct. This struct contains details returned by Omise's REST API. You can inspect the Code or StatusCode fields to implement specific error handling logic for different failure scenarios (e.g., authentication failures, validation errors, or rate limiting).

// Example of checking for a specific API error code
err := client.Charge(params)
if err != nil {
	if apiErr, ok := err.(*omise.Error); ok {
		if apiErr.Code == "card_declined" {
			// Handle declined card specifically
		}
	}
}

The Omise Go library provides various List types (e.g., AccountList, ChargeList, CustomerList) that represent paginated responses from the Omise REST API. Each list type includes a Find(id string) method. This method iterates through the Data slice and returns the resource with the matching ID. If no resource with the provided ID is found within that specific list, the method returns nil.

// Example usage pattern (conceptual)
// Assuming 'chargeList' is an instance of ChargeList retrieved from the API
charge := chargeList.Find("chrg_test_12345")
if charge != nil {
    // Use the charge object
}

The Do(result interface{}, operation internal.Operation) method is the primary way to perform API requests. It executes the provided operation and unmarshals the JSON response into the result parameter.

If the operation is successful, result will contain the response data. If it fails, a non-nil error is returned, which may be of type *omise.Error. You can inspect the Code and Message fields of the error for more details.

// Example usage with an operation (assuming 'operation' is defined elsewhere)
var result MyResponseStruct
err := client.Do(&result, operation)
if err != nil {
    // handle error
}