Checkout.com Golang SDK

Getting started

Version 3.0.0 is here!



The module path is now github.com/checkout/checkout-sdk-go/v3, so update your imports when you upgrade.

Your merchant-specific subdomain is now required: call WithEnvironmentSubdomain(), or the deprecated WithLegacyDomain() to keep using the shared hosts.

context.Context support from 2.0.0 is unchanged: every client method still has a *WithContext variant, and the plain methods keep working.

Module installer

Make sure your project is using Go Modules:

# For v3.x (current)
go get github.com/checkout/checkout-sdk-go/v3

# For v1.x (legacy)
go get github.com/checkout/checkout-sdk-go@v1.9.0

Then import the library into your code:

# For v3.x
import "github.com/checkout/checkout-sdk-go/v3"

# For v1.x
import "github.com/checkout/checkout-sdk-go"

:rocket: Please check in GitHub releases for all the versions available.

:book: Checkout our official documentation.

• Official Docs (Default)
• Official Docs (Previous)

:books: Check out our official API documentation guide, where you can also find more usage examples.

• API Reference (Default)
• API Reference (Previous)

How to use the SDK

This SDK can be used with two different pair of API keys provided by Checkout. However, using different API keys imply
using specific API features.

Please find in the table below the types of keys that can be used within this SDK.

Account System	Public Key (example)	Secret Key (example)
Default	pk_pkhpdtvabcf7hdgpwnbhw7r2uic	sk_m73dzypy7cf3gf5d2xr4k7sxo4e
Previous	pk_g650ff27-7c42-4ce1-ae90-5691a188ee7b	sk_gk3517a8-3z01-45fq-b4bd-4282384b0a64

Note: sandbox keys have a sbox_ or test_ identifier, for Default and Previous accounts respectively.

If you don’t have your own API keys, you can sign up for a test
account here.

PLEASE NEVER SHARE OR PUBLISH YOUR CHECKOUT CREDENTIALS.

Subdomain value

Requests must be made through your merchant-specific subdomain (MSSD): the first 8 characters of your client ID (excluding cli_). For example, if your client ID is cli_vkuhvk4vjn2edkps7dfsq6emqm, your subdomain is vkuhvk4v. When WithEnvironmentSubdomain is set the SDK sends requests to https://vkuhvk4v.api.checkout.com. See Base URLs and API endpoints for further details, and for where to find your unique client ID. Private Link merchants use their pl- prefixed subdomain (for example pl-vkuhvk4v), which the SDK also accepts.

Default

Default keys client instantiation can be done as follows:

import (
    "github.com/checkout/checkout-sdk-go/v3"
    "github.com/checkout/checkout-sdk-go/v3/configuration"
)

api, err := checkout.Builder().
                     StaticKeys().
                     WithEnvironment(configuration.Sandbox()).
                     WithEnvironmentSubdomain("subdomain"). // required, the first 8 characters of your client ID
                     WithSecretKey("secret_key").
                     WithPublicKey("public_key"). // optional, only required for operations related with tokens
                     Build()

Default OAuth

The SDK supports client credentials OAuth, when initialized as follows:

import (
    "github.com/checkout/checkout-sdk-go/v3"
    "github.com/checkout/checkout-sdk-go/v3/configuration"
)

api, err := checkout.Builder().
                     OAuth().
                     WithClientCredentials("client_id", "client_secret").
                     WithEnvironment(configuration.Sandbox()).
                     WithEnvironmentSubdomain("subdomain"). // required, the first 8 characters of your client ID
                     WithScopes(getOAuthScopes()).
                     Build()

Previous

If your pair of keys matches the previous system type, this is how the SDK should be used:

import (
    "github.com/checkout/checkout-sdk-go/v3"
    "github.com/checkout/checkout-sdk-go/v3/configuration"
)

api, err := checkout.Builder().
                     Previous().
                     WithEnvironment(configuration.Sandbox()).
                     WithEnvironmentSubdomain("subdomain"). // optional for the Previous platform
                     WithSecretKey("secret_key").
                     WithPublicKey("public_key"). // optional, only required for operations related with tokens
                     Build()

Then just get any client, and start making requests:

import (
    "github.com/checkout/checkout-sdk-go/v3/payments"
    "github.com/checkout/checkout-sdk-go/v3/payments/nas"
)

request := nas.PaymentRequest{}
response, err := api.Payments.RequestPayment(request)

Error Handling

All the API responses that do not fall in the 2** status codes will return a errors.CheckoutApiError. The
error encapsulates the StatusCode, Status and a the ErrorDetails, if available.

Custom Http Client

Go SDK supports your own configuration for http client using http.Client from the standard library. You can pass it through when instantiating the SDK as follows:

import (
    "net/http"
    
    "github.com/checkout/checkout-sdk-go/v3"
    "github.com/checkout/checkout-sdk-go/v3/configuration"
)

httpClient := http.Client{
    Timeout: time.Duration(20) * time.Millisecond,
}

api, err := checkout.Builder().
                     StaticKeys().
                     WithEnvironment(configuration.Sandbox()).
                     WithHttpClient(&httpClient).
                     WithSecretKey("secret_key")).
                     WithPublicKey("public_key")). // optional, only required for operations related with tokens
                     Build()

Logging

The SDK supports custom Log provider. You can provide your log configuration via SDK initialization. By default, the SDK uses the log package from the standard library.

import (
    "log"	
	
    "github.com/checkout/checkout-sdk-go/v3"
    "github.com/checkout/checkout-sdk-go/v3/configuration"
)

logger := log.New(os.Stderr, "checkout-sdk-go - ", log.LstdFlags)

api, err := checkout.Builder().
                     StaticKeys().
                     WithEnvironment(configuration.Sandbox()).
                     WithSecretKey("secret_key")).
                     WithPublicKey("public_key")). // optional, only required for operations related with tokens
                     WithLogger(logger) // your own custom configuration
                     Build()

Custom Environment

In case that you want to use an integrator or mock server, you can specify your own URI configuration as follows:

import (
    "github.com/checkout/checkout-sdk-go/v3"
    "github.com/checkout/checkout-sdk-go/v3/configuration"
)

environment := configuration.NewEnvironment(
	"https://the.base.uri/", // the uri for all CKO operations
	"https://the.oauth.uri/connect/token", // the uri used for OAUTH authorization, only required for OAuth operations
	"https://the.files.uri/", // the uri used for Files operations, only required for Accounts module
	"https://the.transfers.uri/", // the uri used for Transfer operations, only required for Transfers module
	"https://the.balances.uri/", // the uri used for Balances operations, only required for Balances module
	"https://the.forward.uri/", // the uri used for Forward operations, only required for Forward module
	"https://the.identity.uri/", // the uri used for Identity operations, only required for Identity modules (applicants, identity-verifications, aml-verifications, face-authentications, id-document-verifications)
	false, // isSandbox
)

api, err := checkout.Builder().
                     StaticKeys().
                     WithEnvironment(environment).
                     WithSecretKey("secret_key")).
                     WithPublicKey("public_key")). // optional, only required for operations related with tokens
                     Build()

Building from source

Once you check out the code from GitHub, the project can be built using:

go mod tidy

go build

The execution of integration tests require the following environment variables set in your system:

• For default account systems (NAS): CHECKOUT_DEFAULT_PUBLIC_KEY & CHECKOUT_DEFAULT_SECRET_KEY
• For default account systems (OAuth): CHECKOUT_DEFAULT_OAUTH_CLIENT_ID & CHECKOUT_DEFAULT_OAUTH_CLIENT_SECRET
• For Previous account systems (ABC): CHECKOUT_PREVIOUS_PUBLIC_KEY & CHECKOUT_PREVIOUS_SECRET_KEY

Telemetry

Request telementry is enabled by default in the Go SDK. Request latency is included in the telemetry data. Recording the request latency allows Checkout.com to continuously monitor and imporove the merchant experience.

Request telemetry can be disabled by opting out during checkout_sdk_builder builder step:

api := checkout.Builder().
    Previous().
    WithSecretKey("CHECKOUT_PREVIOUS_SECRET_KEY").
    WithEnvironment(configuration.Sandbox()).
    WithEnableTelemetry(false).
    Build()

Legacy domain (emergency use only)

:warning: Only use if merchant specific sub domains are causing issues. Connecting through your merchant-specific subdomain (see Subdomain value) is the supported way of using the Checkout.com API, and non-subdomain usage will be deprecated.

If, in exceptional circumstances, you cannot use your merchant-specific subdomain, you can explicitly opt out by calling WithLegacyDomain() instead of WithEnvironmentSubdomain(...):

api, err := checkout.Builder().
                     StaticKeys().
                     WithEnvironment(configuration.Sandbox()).
                     WithSecretKey("secret_key").
                     WithLegacyDomain(). // deprecated, emergency fallback only
                     Build()

This routes requests to api.checkout.com (or api.sandbox.checkout.com) and access.checkout.com (or access.sandbox.checkout.com). The method carries a Deprecated: doc comment, so staticcheck (SA1019) and editors will flag it. Exactly one of WithEnvironmentSubdomain(...) or WithLegacyDomain() must be set: Build() returns a CheckoutArgumentError if both, or neither, are. The Previous (ABC) platform predates merchant-specific subdomains and is exempt from this requirement.

Code of Conduct

Please refer to Code of Conduct

Licensing

MIT