dominaite

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 20, 2026 License: MIT Imports: 16 Imported by: 0

README

dominaite-go

Server-side Go client for the Dominaite merchant API. One call from your backend opens a hosted checkout session; a two-line script tag renders the payment widget on your page. Card details go straight from your customer's browser into the payment widget - they never touch your server, which keeps your PCI scope minimal (SAQ A).

Go 1.21 or newer. Zero dependencies: crypto/hmac, crypto/sha256, net/http, encoding/json, all standard library.

Install

The module path is github.com/dominaite/merchant-sdk-go, and it is a placeholder: the repo does not exist yet and the final name is an open owner decision. npm settled on @dominaite/merchant-sdk and PyPI on dominaite (2026-08-17), so whatever repo this lands in should keep the same family. Until the repo exists, use a local checkout with a replace:

go mod edit -require=github.com/dominaite/merchant-sdk-go@v0.0.0
go mod edit -replace=github.com/dominaite/merchant-sdk-go=/path/to/dominaite-go-sdk
go mod tidy

Once the repo is published, drop the replace and go get it normally.

To work on the SDK itself:

cd dominaite-go-sdk
go vet ./...
go test ./...      # includes the offline signing vector

Credentials

You get two values from the Dominaite dashboard, Website integration tab, when you generate an API key (shown once - store them like passwords):

  • dmk_... - your API key id. Identifies you; not secret by itself.
  • dms_... - your API secret. Server-side only: environment variable or a config file outside the web root. Never in a browser, never in git, never in logs.

Every request is signed with the secret (HMAC-SHA256) and timestamped. Keep your server clock on NTP - signatures older than 5 minutes are rejected with TIMESTAMP_OUT_OF_RANGE.

If the key has an IP allowlist, calls from anywhere else fail with IP_NOT_ALLOWED. The allowlist is managed on the same dashboard tab.

Quickstart (zero to a signed session against dev)

Everything below is copy-paste. It assumes an empty directory and nothing installed.

mkdir my-checkout && cd my-checkout
go mod init example.com/my-checkout
go mod edit -require=github.com/dominaite/merchant-sdk-go@v0.0.0
go mod edit -replace=github.com/dominaite/merchant-sdk-go=/path/to/dominaite-go-sdk
go mod tidy

Set your credentials and the environment you are pointing at:

export DOMINAITE_KEY_ID=dmk_...      # Website integration tab
export DOMINAITE_SECRET=dms_...      # shown once when you generated the key
# Dev: the payments function app, whose Azure Functions route prefix is /api.
# Confirm the host for your environment before the first call.
export DOMINAITE_BASE_URL=https://func-dom-gw-payments-dev-gwc-01.azurewebsites.net/api
# Production needs no DOMINAITE_BASE_URL - the SDK defaults to
# https://api.dominaite.com/payments

main.go:

package main

import (
	"context"
	"errors"
	"fmt"
	"os"

	dominaite "github.com/dominaite/merchant-sdk-go"
)

func main() {
	client, err := dominaite.New(
		os.Getenv("DOMINAITE_KEY_ID"),
		os.Getenv("DOMINAITE_SECRET"),
		dominaite.WithBaseURL(os.Getenv("DOMINAITE_BASE_URL")), // ignored when empty
	)
	if err != nil {
		panic(err)
	}

	session, err := client.CreateCheckoutSession(context.Background(), dominaite.CreateCheckoutSessionParams{
		Amount:         2500,          // minor units: 2500 = 25.00 EUR
		Currency:       "EUR",
		OrderReference: "order-1042",  // your own order id, shows up in your dashboard
		Customer: &dominaite.Customer{
			// Pass everything you already know - prefilled fields are hidden from the
			// payer, so the checkout form stays short.
			FirstName: "Ana",
			LastName:  "Kirova",
			Email:     "ana@example.com",
		},
		Language: "bg",   // widget UI language
		Theme:    "dark",
	})
	if err != nil {
		var refusal *dominaite.RefusalError
		var transport *dominaite.TransportError
		switch {
		case errors.As(err, &refusal):
			// Machine-readable: refusal.ErrorCode - codes listed below.
			fmt.Println("Payment unavailable:", refusal.ErrorCode)
		case errors.As(err, &transport):
			// Network blip - safe to retry with the same idempotency key.
			fmt.Println("Payment temporarily unavailable")
		default:
			panic(err)
		}
		return
	}

	// Store session.TransactionID against your order, then hand CashierKey +
	// CashierToken to the page that renders the widget.
	fmt.Printf("%+v\n", session)
}
go run .

A successful run prints TransactionID, OrderID, CashierKey, CashierToken, Amount, Currency, ExpiresAt. Render the widget with the two cashier values:

<div id="checkout"></div>
<script src="https://bp-checkout.dominaite.com/v2/launcher"
        data-cashier-key="CASHIER_KEY_FROM_SESSION"
        data-cashier-token="CASHIER_TOKEN_FROM_SESSION"></script>

CashierKey and CashierToken are per-payment session values, not credentials - but HTML-escape them when you template them into the page (html/template does it for you).

That's the whole integration: the session call, the script tag, and your domain bound to your checkout by Dominaite during onboarding.

There is a runnable version of the above in examples/create-session/main.go in this repo - it mints a session and reads the status back, using the same three environment variables:

go run ./examples/create-session

Client options

dominaite.New(keyID, secret, opts...) takes functional options:

Option What
WithBaseURL(url) Point at a non-production environment. Empty values are ignored, so an unset env var still gives you production.
WithTimeout(d) Per-request timeout on the default HTTP client. Defaults to 45s (serverless cold starts can take 10+s).
WithHTTPClient(c) Your own *http.Client: proxy-aware transport, custom TLS, a test double. Replaces WithTimeout.
WithUserAgent(s) Appends your identifier to the SDK's User-Agent, which helps when support reads the access logs.

Every call takes a context.Context. A context deadline shorter than the client timeout wins, and cancelling the context returns a *TransportError wrapping context.Canceled.

Amounts are minor units

Amount is always an integer in the currency's minor unit: 2500 is 25.00 EUR. The field is an int64, so a float will not compile; non-positive values are rejected before anything reaches the network. The amount is locked server-side - what you pass here is what gets charged; nothing in the browser can change it.

Retries and double-charges

Every CreateCheckoutSession call carries an idempotency key (auto-generated, or set your own in IdempotencyKey). Retrying with the same key never opens a second payment - on a timeout, retry with the same key rather than generating a new one.

CreateCheckoutSessionWithRetry does that for you: it pins one key up front and reuses it across attempts, retrying only *TransportError (network failures and 5xx, including MERCHANT_API_UNAVAILABLE). Refusals and authentication failures are not retried - they will not change.

session, err := client.CreateCheckoutSessionWithRetry(
	ctx,
	dominaite.CreateCheckoutSessionParams{Amount: 2500, Currency: "EUR", OrderReference: "order-1042"},
	dominaite.RetryOptions{Attempts: 3, BaseDelay: 500 * time.Millisecond}, // zero values use these defaults
)

The delay doubles each attempt, and a cancelled context stops the wait immediately.

Sessions expire

A session is valid for 2 hours. If the payer comes back later, create a new session.

Status polling

status, err := client.GetStatus(ctx, session.TransactionID)
// status.Status == "succeeded", status.OrderReference == "order-1042",
// status.Amount == 2500, status.Currency == "EUR", ...

Status is one of pending, processing, succeeded, failed, refunded, partially_refunded, cancelled, disputed, abandoned (exported as the Status* constants). While the session is still payable the response also carries ExpiresAt; after that instant a pending session can only become abandoned. An unknown transaction id returns an *APIError with HTTPStatus 404.

Poll after the payer returns to you, or on your order timeout - not in a tight loop; the endpoint is rate limited per key.

Both response types also carry Raw (json.RawMessage) with the unparsed payload, for fields the structs do not model yet.

Errors

Every error the SDK returns satisfies the dominaite.Error interface and matches errors.Is(err, dominaite.ErrDominaite), so one catch-all works:

var sdkErr dominaite.Error
if errors.As(err, &sdkErr) { ... }

For the specific kind, use errors.As with the concrete pointer type:

Error When What to do
*RefusalError The API answered with success: false. ErrorCode carries the reason. Branch on ErrorCode. Do not blind-retry.
*AuthError 401/403. ErrorCode is INVALID_API_KEY, INVALID_SIGNATURE, TIMESTAMP_OUT_OF_RANGE, or IP_NOT_ALLOWED. Fix the key id, secret, server clock, or allowlist. Never retry-loop.
*TransportError Network failure, timeout, or 5xx (MERCHANT_API_UNAVAILABLE). Wraps the cause, reachable with errors.Unwrap. Retry with the same idempotency key.
*APIError Any other rejecting or unexpected response; HTTPStatus carries the code. Inspect. A 422 means an idempotency key was replayed with a different body - use a fresh key.
*ValidationError Bad arguments (non-positive amount, missing field, malformed key id). Fix the call; nothing was sent.

Refusal codes on RefusalError.ErrorCode:

  • PAYMENT_PROCESSING_UNAVAILABLE - card payments are off right now; retry later.
  • DUPLICATE_REQUEST - a session for this idempotency key is already open.
  • ALREADY_PROCESSED - this idempotency key's payment already completed.
  • IDEMPOTENCY_KEY_REUSED - same key sent with a different body; use a fresh key.

Verifying your signing

Run go test ./... before you touch the live API. The SDK signs for you, but the recipe is pinned by an offline known-answer vector shared with the gateway and the dashboard, and the suite reproduces it byte-for-byte. If that test fails, nothing else matters.

If you ever hand-roll the signing (or debug an INVALID_SIGNATURE), Sign is exported:

dominaite.Sign(dominaite.SignInput{
	Secret:         "dms_...",
	Timestamp:      "1755302400",                                 // unix SECONDS
	Method:         "POST",
	Path:           "/merchant-api/bridgerpay/checkout/sessions",  // path only, no host
	IdempotencyKey: "00000000-0000-4000-8000-000000000001",        // "" for GET
	Body:           `{"amount":2500,"currency":"EUR","orderReference":"order-1042"}`, // "" for GET
})
// "95759958a0a0a9bd3e6e37101c01e8e7fee1166406e4ac2ff488764f5f742cbf"

The signed payload is five lines: "{timestamp}\n{METHOD}\n{path}\n{idempotencyKey}\n{sha256hex(body)}", signed as lowercase hex HMAC-SHA256 with your secret, UTF-8 throughout. GET signs an empty idempotency key and an empty body, and sends no Idempotency-Key header.

Documentation

Overview

Package dominaite is the server-side Go client for the Dominaite merchant API.

One call from your backend opens a hosted checkout session; a two-line script tag renders the payment widget on your page. Card details go straight from your customer's browser into the widget. They never touch your server or this SDK, which keeps your PCI scope minimal (SAQ A).

Keep your API secret on the server. Never ship it to a browser, never commit it, never log it.

client, err := dominaite.New(os.Getenv("DOMINAITE_KEY_ID"), os.Getenv("DOMINAITE_SECRET"))
if err != nil {
	return err
}
session, err := client.CreateCheckoutSession(ctx, dominaite.CreateCheckoutSessionParams{
	Amount:         2500, // minor units: 25.00 EUR
	Currency:       "EUR",
	OrderReference: "order-1042",
})

Hand session.CashierKey and session.CashierToken to the embed snippet.

Index

Constants

View Source
const (
	// DefaultBaseURL is the production merchant API.
	DefaultBaseURL = "https://api.dominaite.com/payments"

	// SessionsPath is the canonical path that gets signed. POST creates a
	// session; GET SessionsPath + "/{transactionId}" reads its status.
	SessionsPath = "/merchant-api/bridgerpay/checkout/sessions"

	// Version is this SDK's version, reported in the User-Agent.
	Version = "0.1.0"
)
View Source
const (
	StatusPending           = "pending"
	StatusProcessing        = "processing"
	StatusSucceeded         = "succeeded"
	StatusFailed            = "failed"
	StatusRefunded          = "refunded"
	StatusPartiallyRefunded = "partially_refunded"
	StatusCancelled         = "cancelled"
	StatusDisputed          = "disputed"
	StatusAbandoned         = "abandoned"
)

Transaction status values returned by GetStatus.

Variables

View Source
var ErrDominaite = errors.New("dominaite")

ErrDominaite matches every error this SDK returns, for a single errors.Is catch-all:

if errors.Is(err, dominaite.ErrDominaite) { ... }

For the specific kind, use errors.As with *RefusalError, *AuthError, *APIError, *TransportError or *ValidationError, or errors.As with the Error interface to catch any of them while keeping the message.

Functions

func Sign

func Sign(in SignInput) string

Sign builds the X-Signature value for one request: lowercase hex HMAC-SHA256 over

"{timestamp}\n{METHOD}\n{path}\n{idempotencyKey}\n{sha256hex(body)}"

The idempotency key is INSIDE the signature, so a captured request cannot be replayed with a different key to mint extra sessions. The server rejects timestamps more than 5 minutes off, so keep your server clock on NTP.

The client signs for you. Sign is exported so you can pin the recipe against the offline test vector before calling the live API, and so you can debug an INVALID_SIGNATURE without reading this package's source.

Types

type APIError

type APIError struct {
	HTTPStatus int
	// contains filtered or unexported fields
}

APIError means the API answered, but with an unexpected or rejecting response. HTTPStatus carries the code. A 422 means an idempotency key was replayed with a different body; use a fresh key. A 404 from GetStatus means an unknown transaction id.

func (APIError) Error

func (e APIError) Error() string

func (APIError) Is

func (e APIError) Is(target error) bool

Is makes errors.Is(err, ErrDominaite) true for every SDK error.

type AuthError

type AuthError struct {
	ErrorCode string
	// contains filtered or unexported fields
}

AuthError means the API rejected your credentials or signature (HTTP 401/403). Not retryable: fix the key id, the secret, the server clock, or the caller allowlist.

ErrorCode is one of INVALID_API_KEY, INVALID_SIGNATURE, TIMESTAMP_OUT_OF_RANGE, IP_NOT_ALLOWED.

func (AuthError) Error

func (e AuthError) Error() string

func (AuthError) Is

func (e AuthError) Is(target error) bool

Is makes errors.Is(err, ErrDominaite) true for every SDK error.

type CheckoutSession

type CheckoutSession struct {
	TransactionID string `json:"transactionId"`
	OrderID       string `json:"orderId"`
	// CashierKey feeds the widget's data-cashier-key. A per-payment value, not
	// a credential.
	CashierKey string `json:"cashierKey"`
	// CashierToken feeds the widget's data-cashier-token. A per-payment value,
	// not a credential.
	CashierToken string `json:"cashierToken"`
	// Amount is in MINOR units.
	Amount   int64  `json:"amount"`
	Currency string `json:"currency"`
	// ExpiresAt is ISO 8601. Sessions are valid for 2 hours.
	ExpiresAt string `json:"expiresAt"`

	// Raw is the unparsed payload, for fields this struct does not model yet.
	Raw json.RawMessage `json:"-"`
}

CheckoutSession is what CreateCheckoutSession returns.

type CheckoutStatus

type CheckoutStatus struct {
	TransactionID  string `json:"transactionId"`
	OrderID        string `json:"orderId"`
	OrderReference string `json:"orderReference,omitempty"`
	// Status is one of the Status* constants.
	Status string `json:"status"`
	// Amount is in MINOR units.
	Amount         int64  `json:"amount"`
	Currency       string `json:"currency"`
	RefundedAmount int64  `json:"refundedAmount,omitempty"`
	CreatedAt      string `json:"createdAt"`
	UpdatedAt      string `json:"updatedAt,omitempty"`
	// ExpiresAt is present while the session is still payable.
	ExpiresAt string `json:"expiresAt,omitempty"`

	// Raw is the unparsed payload, for fields this struct does not model yet.
	Raw json.RawMessage `json:"-"`
}

CheckoutStatus is what GetStatus returns.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a server-side client for the Dominaite merchant API. It is safe for concurrent use.

func New

func New(keyID, secret string, opts ...Option) (*Client, error)

New builds a client from your API key id (dmk_...) and secret (dms_...), both from the dashboard's Website integration tab. It returns a *ValidationError when either credential has the wrong prefix, which catches a swapped key id and secret before anything is sent.

func (*Client) CreateCheckoutSession

func (c *Client) CreateCheckoutSession(ctx context.Context, params CreateCheckoutSessionParams) (*CheckoutSession, error)

CreateCheckoutSession opens a hosted checkout session for one payment.

Errors it returns:

  • *ValidationError: bad arguments; nothing was sent.
  • *AuthError: wrong credentials, bad signature, clock off, IP not allowlisted. Fix the config, do not retry.
  • *RefusalError: the gateway refused the session; inspect ErrorCode.
  • *APIError: an unexpected or rejecting response; inspect HTTPStatus.
  • *TransportError: network failure or 5xx. Safe to retry WITH the same idempotency key, which is what CreateCheckoutSessionWithRetry does.

func (*Client) CreateCheckoutSessionWithRetry

func (c *Client) CreateCheckoutSessionWithRetry(ctx context.Context, params CreateCheckoutSessionParams, opts RetryOptions) (*CheckoutSession, error)

CreateCheckoutSessionWithRetry creates a session, retrying *TransportError only, with THE SAME idempotency key across every attempt.

Reusing the key is what makes the retry safe. A transport failure leaves you not knowing whether the request landed; the API returns the original session for a key it has already seen instead of opening a second one. Generating a fresh key per attempt would be exactly the double-charge bug this method exists to prevent, so the key is pinned once before the first attempt.

Refusals and authentication failures are returned immediately. They will not change on a retry.

func (*Client) GetStatus

func (c *Client) GetStatus(ctx context.Context, transactionID string) (*CheckoutStatus, error)

GetStatus reads the payment status of one of your checkout sessions.

Status is one of the Status* constants. While a session is still payable the response also carries ExpiresAt; after that instant a pending session can only become abandoned. Amounts are integers in MINOR units. An unknown transaction id returns an *APIError with HTTPStatus 404.

Poll after the payer returns to you, or on your order timeout. Not in a tight loop: the endpoint is rate limited per key.

type CreateCheckoutSessionParams

type CreateCheckoutSessionParams struct {
	// Amount is in MINOR units: 2500 is 25.00 EUR. Integers only.
	Amount int64 `json:"amount"`
	// Currency is ISO 4217, e.g. "EUR".
	Currency string `json:"currency"`
	// OrderReference is your own order id, at most 100 characters. It shows up
	// in your dashboard.
	OrderReference string `json:"orderReference"`

	Customer *Customer `json:"customer,omitempty"`
	// Country is ISO 3166-1 alpha-2.
	Country string `json:"country,omitempty"`
	// Language is the ISO 639-1 widget UI language.
	Language string `json:"language,omitempty"`
	// Theme is "light", "dark" or "bright".
	Theme       string `json:"theme,omitempty"`
	Description string `json:"description,omitempty"`

	// IdempotencyKey is auto-generated when empty. It travels in the header and
	// in the signature, never in the body. Retrying with the same key never
	// creates a second payment, so on a timeout retry with the same key.
	IdempotencyKey string `json:"-"`

	// Extra carries any additional field the API accepts that this struct does
	// not model yet. Keys here are merged into the JSON body.
	Extra map[string]any `json:"-"`
}

CreateCheckoutSessionParams are the parameters for Client.CreateCheckoutSession. Amount, Currency and OrderReference are required.

func (CreateCheckoutSessionParams) MarshalJSON

func (p CreateCheckoutSessionParams) MarshalJSON() ([]byte, error)

MarshalJSON emits the request body: the modelled fields in declaration order, with Extra merged in. IdempotencyKey is excluded; it is a header, not a body field.

type Customer

type Customer struct {
	FirstName string `json:"firstName,omitempty"`
	LastName  string `json:"lastName,omitempty"`
	Email     string `json:"email,omitempty"`
	Phone     string `json:"phone,omitempty"`
}

Customer holds optional payer details. Prefilled fields are hidden from the payer in the widget, so the checkout form stays short.

type Error

type Error interface {
	error
	// contains filtered or unexported methods
}

Error is implemented by every error this SDK returns. It is sealed: only the types in this package satisfy it, so a type switch over them is exhaustive.

var apiErr dominaite.Error
if errors.As(err, &apiErr) { ... }

type Option

type Option func(*Client)

Option configures a Client. Pass options to New.

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL points the client at a non-production environment. Trailing slashes are trimmed. Empty values are ignored, so you can pass an unset environment variable straight through and still get production.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient supplies your own *http.Client: a proxy-aware transport, custom TLS, or a test double. It replaces WithTimeout, so set the timeout on the client you pass.

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout sets the per-request timeout on the default HTTP client. Defaults to 45 seconds. A context deadline still wins when it is shorter.

func WithUserAgent

func WithUserAgent(userAgent string) Option

WithUserAgent appends your own identifier to the SDK's User-Agent, which helps when Dominaite support reads the access logs for your integration.

type RefusalError

type RefusalError struct {
	ErrorCode string
	// contains filtered or unexported fields
}

RefusalError means the gateway understood the request but refused to open a checkout session. The API answered with success: false.

Branch on ErrorCode:

  • PAYMENT_PROCESSING_UNAVAILABLE: card payments are off right now; retry later.
  • DUPLICATE_REQUEST: a session for this idempotency key is already open.
  • ALREADY_PROCESSED: this idempotency key's payment already completed.
  • IDEMPOTENCY_KEY_REUSED: same key sent with a DIFFERENT body; use a fresh key.

Never blind-retry a refusal. It will not change on its own.

func (RefusalError) Error

func (e RefusalError) Error() string

func (RefusalError) Is

func (e RefusalError) Is(target error) bool

Is makes errors.Is(err, ErrDominaite) true for every SDK error.

type RetryOptions

type RetryOptions struct {
	// Attempts is the total number of attempts including the first. Zero means
	// the default of 3.
	Attempts int
	// BaseDelay is the wait before the first retry; it doubles each attempt.
	// Zero means the default of 500ms.
	BaseDelay time.Duration
}

RetryOptions tunes CreateCheckoutSessionWithRetry.

type SignInput

type SignInput struct {
	// Secret is your API secret (dms_...).
	Secret string
	// Timestamp is unix SECONDS, as sent in X-Timestamp.
	Timestamp string
	// Method is the HTTP method. Uppercased before signing.
	Method string
	// Path is the canonical path only: no host, no query string.
	Path string
	// IdempotencyKey is the Idempotency-Key header value. Empty string for GET.
	IdempotencyKey string
	// Body is the exact request body string that will be sent. Empty string for GET.
	Body string
}

SignInput is everything that goes into one request signature.

type TransportError

type TransportError struct {
	Err error
	// contains filtered or unexported fields
}

TransportError means a network-level failure, a timeout, or a 5xx. The request may or may not have reached the API, so retry WITH THE SAME idempotency key: a retried key never creates a second payment. CreateCheckoutSessionWithRetry does exactly that.

Err is the underlying cause when there was one, reachable with errors.Unwrap or errors.As.

func (TransportError) Error

func (e TransportError) Error() string

func (TransportError) Is

func (e TransportError) Is(target error) bool

Is makes errors.Is(err, ErrDominaite) true for every SDK error.

func (*TransportError) Unwrap

func (e *TransportError) Unwrap() error

Unwrap exposes the underlying network error, if any.

type ValidationError

type ValidationError struct {
	// contains filtered or unexported fields
}

ValidationError means the SDK rejected the call before sending anything. Nothing reached the network; fix the arguments.

func (ValidationError) Error

func (e ValidationError) Error() string

func (ValidationError) Is

func (e ValidationError) Is(target error) bool

Is makes errors.Is(err, ErrDominaite) true for every SDK error.

Directories

Path Synopsis
examples
create-session command
Command create-session mints a Dominaite checkout session and reads its status back.
Command create-session mints a Dominaite checkout session and reads its status back.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL