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
- Variables
- func Sign(in SignInput) string
- type APIError
- type AuthError
- type CheckoutSession
- type CheckoutStatus
- type Client
- func (c *Client) CreateCheckoutSession(ctx context.Context, params CreateCheckoutSessionParams) (*CheckoutSession, error)
- func (c *Client) CreateCheckoutSessionWithRetry(ctx context.Context, params CreateCheckoutSessionParams, opts RetryOptions) (*CheckoutSession, error)
- func (c *Client) GetStatus(ctx context.Context, transactionID string) (*CheckoutStatus, error)
- func (c Client) GoString() string
- func (c *Client) Ping(ctx context.Context) (*Ping, error)
- func (c Client) String() string
- type CreateCheckoutSessionParams
- type Customer
- type Error
- type Option
- type Ping
- type RateLimitError
- type RefusalError
- type RetryOptions
- type SignInput
- type TransportError
- type ValidationError
- type VerifyOption
- type WebhookData
- type WebhookEvent
- type WebhookVerificationError
Examples ¶
Constants ¶
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/checkout/sessions" // PingPath is the credentials-and-clock smoke test. It creates nothing. PingPath = "/merchant-api/ping" // Version is this SDK's version, reported in the User-Agent. Version = "0.1.2" )
const ( // WebhookReasonMalformedSignature means the signature header was missing, // empty, or not in the "t=...,v1=..." shape (no t, no v1, or a v1 that is // not hex). Nothing could be checked. WebhookReasonMalformedSignature = "MALFORMED_SIGNATURE" // WebhookReasonSignatureMismatch means the MAC did not match. Either the // secret is wrong or the payload is not the bytes that were signed. Treat // the request as hostile. WebhookReasonSignatureMismatch = "SIGNATURE_MISMATCH" // WebhookReasonTimestampOutOfTolerance means the MAC was valid but the // timestamp is too far from now: a replay of a genuine old delivery, or // your server clock has drifted. Check NTP before widening the tolerance. WebhookReasonTimestampOutOfTolerance = "TIMESTAMP_OUT_OF_TOLERANCE" // WebhookReasonMalformedPayload means the signature was good but the body // was not valid JSON. Surprising - the bytes are authentic - so log it // rather than silently dropping it. WebhookReasonMalformedPayload = "MALFORMED_PAYLOAD" // WebhookReasonInvalidTolerance means the caller passed a negative // tolerance to WithWebhookTolerance. That is your bug, not the sender's: // nothing about the delivery was checked. Use 0 to require an exact // timestamp, or a positive window. WebhookReasonInvalidTolerance = "INVALID_TOLERANCE" )
Reasons reported on WebhookVerificationError.Reason.
const ( StatusPending = "pending" StatusProcessing = "processing" StatusSucceeded = "succeeded" StatusFailed = "failed" StatusRefunded = "refunded" StatusPartiallyRefunded = "partially_refunded" StatusCancelled = "cancelled" StatusDisputed = "disputed" StatusRequiresCapture = "requires_capture" StatusAbandoned = "abandoned" )
Transaction status values returned by GetStatus.
const ( EventPaymentSucceeded = "payment.succeeded" EventPaymentFailed = "payment.failed" EventPaymentRequiresCapture = "payment.requires_capture" EventPaymentCancelled = "payment.cancelled" EventPaymentAbandoned = "payment.abandoned" EventPaymentRefunded = "payment.refunded" EventPaymentDisputed = "payment.disputed" )
Webhook event types. This is the complete v1 catalog - endpoint registration rejects anything outside it, and the match is case-sensitive.
EventPaymentSucceeded is the ONLY signal that means money is in hand. The in-flight states (pending, processing) are deliberately not webhooked; poll GetStatus if you want to drive UX off them.
const DefaultWebhookTolerance = 5 * time.Minute
DefaultWebhookTolerance is how far a delivery's timestamp may sit from your clock before VerifyWebhook rejects it. It matches the gateway's own window.
const WebhookSignatureHeader = "X-Webhook-Signature"
WebhookSignatureHeader is the header Dominaite signs each delivery with. An endpoint can be configured to use a different header name, but this is the default and the one the dashboard shows.
Variables ¶
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, *RateLimitError, *APIError, *TransportError or *ValidationError, or errors.As with the Error interface to catch any of them while keeping the message.
var Statuses = []string{ StatusPending, StatusProcessing, StatusSucceeded, StatusFailed, StatusRefunded, StatusPartiallyRefunded, StatusCancelled, StatusDisputed, StatusRequiresCapture, StatusAbandoned, }
Statuses is the complete v1 status vocabulary. A value outside this list means the gateway grew a status this SDK does not know yet: keep polling, never treat it as terminal.
Functions ¶
func Sign ¶
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 ¶
APIError means the API answered, but with an unexpected or rejecting response. HTTPStatus carries the code. A 404 from GetStatus means an unknown transaction id. A 3xx means something in front of the API answered with a redirect: the SDK never follows one and never treats its body as a real response, because the API itself does not redirect.
A key replayed with a different body does NOT arrive here. The API answers HTTP 200 with success false and IDEMPOTENCY_KEY_REUSED, so it reaches you as a *RefusalError. A 429 does not arrive here either: it is a *RateLimitError.
ErrorCode is the machine-readable code when the API sent one, so input rejections can be branched on rather than string-matched. A 400 carrying IDEMPOTENCY_KEY_REQUIRED means the Idempotency-Key header was missing or empty. Empty when the API named no code.
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.
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 ¶
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, and when WithBaseURL was given a non-https URL outside loopback.
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.
- *RateLimitError: HTTP 429; back off and reschedule with the same idempotency key. Not retried for you, by CreateCheckoutSessionWithRetry either.
- *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; a key the API has already seen is refused instead of opening a second session. 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.
A retry after the first attempt DID land does not give you that session back. The API answers with a replay refusal (*RefusalError, ErrorCode DUPLICATE_REQUEST, ALREADY_PROCESSED, PRIOR_ATTEMPT_FAILED or IDEMPOTENCY_KEY_REUSED) and no cashier fields. Recover through RefusalError.TransactionID with GetStatus when the API named one.
Refusals and authentication failures are returned immediately. They will not change on a retry.
Rate limits (*RateLimitError) are returned immediately too. Retrying into a full queue lengthens it; back off for RetryAfterSeconds and reschedule with the same idempotency key.
func (*Client) GetStatus ¶
GetStatus reads the payment status of one of your checkout sessions.
Status is one of the Status* constants: pending, processing, succeeded, failed, refunded, partially_refunded, cancelled, disputed, requires_capture, abandoned. 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.
StatusSucceeded is the only value that means the payment is complete. Keep polling on StatusPending, StatusProcessing and StatusRequiresCapture - none of them is terminal.
StatusRequiresCapture is NOT "unpaid": the payer has already paid and the funds are held awaiting capture. Never treat it as an abandoned order.
Treat any status you do not recognise as still-open too: a value the API adds later should make you keep polling, never silently close a live order.
Poll after the payer returns to you, or on your order timeout. Not in a tight loop: the endpoint is rate limited per key (60/min per key, 120/min per IP), and going over returns a *RateLimitError.
func (*Client) Ping ¶ added in v0.1.2
Ping verifies your credentials, your signing and your clock without creating anything. Make this your first live call: it isolates the setup problems from the payment ones, so a failure here is the key id, the secret, the signature, the clock or an IP allowlist and nothing else.
Check Ping.ClockSkewSeconds. Requests start failing at 300.
Errors it returns:
- *AuthError: wrong credentials, bad signature, clock off, IP not allowlisted.
- *APIError: an unexpected or rejecting response; inspect HTTPStatus.
- *RateLimitError: HTTP 429; back off, the SDK does not retry it for you.
- *TransportError: network failure or 5xx.
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 ¶
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.
The URL must be https://. Plain http:// is accepted only for localhost, 127.0.0.1 and ::1, so a local mock server still works; anything else is refused by New with a *ValidationError. Over http:// your API secret's signature, key id and the whole request body travel in clear text.
func WithHTTPClient ¶
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.
The client is shallow-copied, so the SDK can pin its own redirect policy without changing the behaviour of the client you keep using elsewhere.
func WithTimeout ¶
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 ¶
WithUserAgent appends your own identifier to the SDK's User-Agent, which helps when Dominaite support reads the access logs for your integration.
type Ping ¶ added in v0.1.2
type Ping struct {
// Pong is always true on a 200.
Pong bool `json:"pong"`
// MerchantID is the merchant your key authenticated as.
MerchantID string `json:"merchantId"`
// ServerTime is ISO 8601.
ServerTime string `json:"serverTime,omitempty"`
// ServerUnixTime is the server clock in unix seconds.
ServerUnixTime int64 `json:"serverUnixTime,omitempty"`
// ClockSkewSeconds is server time minus your X-Timestamp. If its absolute
// value creeps toward 300, fix NTP now - requests start failing at 300.
ClockSkewSeconds int64 `json:"clockSkewSeconds"`
// Raw is the unparsed payload, for fields this struct does not model yet.
Raw json.RawMessage `json:"-"`
}
Ping is what Ping returns: proof that your key, secret, signing and clock are all good, without creating anything.
type RateLimitError ¶ added in v0.2.0
type RateLimitError struct {
RetryAfterSeconds int
HasRetryAfter bool
ErrorCode string
// contains filtered or unexported fields
}
RateLimitError means the API answered HTTP 429: you sent requests faster than your allowance. Nothing was created and nothing is wrong with the request.
The platform limits are 60 requests per minute per API key and 120 per minute per IP address. Both are enforced, so several keys behind one egress IP share the second budget.
The SDK does NOT retry this for you, on purpose. A client that retries into a rate limit makes the queue longer for everyone, and only your code knows whether this payment can wait. CreateCheckoutSessionWithRetry returns it immediately too. When you do retry, reuse the SAME idempotency key: the request may have been rejected at the edge, but that is not guaranteed.
RetryAfterSeconds carries the Retry-After header when the API sent one as integer seconds. HasRetryAfter distinguishes "wait 0 seconds" from "the API did not say" - a Retry-After in the HTTP-date form is reported as absent.
var limited *dominaite.RateLimitError
if errors.As(err, &limited) {
wait := 5 * time.Second
if limited.HasRetryAfter {
wait = time.Duration(limited.RetryAfterSeconds) * time.Second
}
// reschedule with the same idempotency key
}
ErrorCode is the machine-readable code when the API named one. Empty otherwise.
type RefusalError ¶
type RefusalError struct {
ErrorCode string
// TransactionID is the payment this idempotency key collided with, when the
// API named one. Empty otherwise.
TransactionID string
// Raw is the unparsed refusal payload, for fields not modelled above.
Raw json.RawMessage
// 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.
- PRIOR_ATTEMPT_FAILED: a prior attempt with this key failed terminally; use a fresh key.
- IDEMPOTENCY_KEY_REUSED: same key sent with a DIFFERENT body; use a fresh key.
On a replay refusal the API also names WHICH payment your key collided with, on TransactionID. That is the recovery path - read it back with GetStatus to find out what the earlier attempt did, instead of minting a second payment for the same order:
session, err := client.CreateCheckoutSession(ctx, params)
var refusal *dominaite.RefusalError
if errors.As(err, &refusal) && refusal.TransactionID != "" {
status, err := client.GetStatus(ctx, refusal.TransactionID)
}
TransactionID is empty when the API did not name one - notably the concurrent-race DUPLICATE_REQUEST, which knows a key was taken but not yet by which row. Always check before using it.
Never blind-retry a refusal. It will not change on its own.
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_...). json:"-" keeps it out of every
// structured JSON logger: those encode the struct rather than calling
// String, so a tag is the only thing that stops them.
Secret string `json:"-"`
// 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) 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.
type VerifyOption ¶ added in v0.2.0
type VerifyOption func(*verifyConfig)
VerifyOption tunes VerifyWebhook. The defaults are correct for production; you should not need any of these outside tests.
func WithWebhookClock ¶ added in v0.2.0
func WithWebhookClock(now func() time.Time) VerifyOption
WithWebhookClock replaces the clock VerifyWebhook compares against. This exists so tests can pin a fixed instant against a recorded delivery; it has no use in production code. A nil function is ignored.
func WithWebhookTolerance ¶ added in v0.2.0
func WithWebhookTolerance(tolerance time.Duration) VerifyOption
WithWebhookTolerance overrides how far the delivery timestamp may sit from your clock. Defaults to DefaultWebhookTolerance (5 minutes).
Zero is the strictest setting, not an off switch: it requires the timestamp to equal your clock to the second, which in practice rejects everything that spent any time in flight. There is no way to disable the freshness check, because doing so accepts a replay of any delivery ever captured. A negative duration is refused outright - VerifyWebhook returns WebhookReasonInvalidTolerance without checking anything.
If you are reaching for this because deliveries keep failing, your server clock is wrong. Fix NTP rather than widening the window.
type WebhookData ¶ added in v0.2.0
type WebhookData struct {
TransactionID string `json:"transactionId"`
// Status is the wire status of the row, one of the Status* constants.
Status string `json:"status"`
// PreviousStatus is the status the row moved from. Nullable on the wire;
// empty string when absent.
PreviousStatus string `json:"previousStatus"`
// Kind is the movement kind, e.g. "sale". Nullable on the wire; empty
// string when absent.
Kind string `json:"kind"`
// Amount is in MINOR units. For payment.* it is what the merchant is PAID
// (the base amount). For payment.refunded it is what was returned to the
// customer. It is NOT the card movement - that is GrossAmount.
Amount int64 `json:"amount"`
// GrossAmount is the card movement in MINOR units: what the customer's card
// was actually charged.
GrossAmount int64 `json:"grossAmount"`
// SurchargeAmount is in MINOR units and nil when no surcharge is known.
// A pointer, so "no surcharge information" stays distinct from "zero".
SurchargeAmount *int64 `json:"surchargeAmount"`
// Currency is ISO 4217.
Currency string `json:"currency"`
// OriginalTransactionID is the parent transaction for refunds and
// reversals. Empty on an original payment.
OriginalTransactionID string `json:"originalTransactionId"`
// IdempotencyKey is your own mint key when the gateway knows it - the
// cheapest way to match a delivery back to your order without a lookup.
// Empty when unknown, which today includes every refund.
IdempotencyKey string `json:"idempotencyKey"`
// Raw is the unparsed data object, for fields not modelled above.
Raw json.RawMessage `json:"-"`
}
WebhookData is the payload of a WebhookEvent.
type WebhookEvent ¶ added in v0.2.0
type WebhookEvent struct {
// ID is the delivery id and YOUR DEDUPE KEY. Delivery is at-least-once, so
// the same ID can arrive more than once and you must ignore the repeats.
ID string `json:"id"`
// Type is one of the Event* constants. Treat an unrecognised type as a
// no-op rather than an error; the catalog can grow.
Type string `json:"type"`
// CreatedAt is the ISO 8601 UTC instant of the transition, not of delivery.
// On a retry it still carries the original transition time.
CreatedAt string `json:"createdAt"`
Data WebhookData `json:"data"`
// Raw is the exact verified payload, byte for byte as signed. Use it for
// fields this struct does not model yet, or to store the delivery verbatim.
Raw json.RawMessage `json:"-"`
}
WebhookEvent is one verified webhook delivery. VerifyWebhook returns it; there is no other way to get one, which is the point - the signature is checked before the body is parsed.
The envelope is FLAT. There is no ApiResponse wrapper and no `success` field, so do not branch on one.
func VerifyWebhook ¶ added in v0.2.0
func VerifyWebhook(payload []byte, signatureHeader, secret string, opts ...VerifyOption) (*WebhookEvent, error)
VerifyWebhook authenticates one webhook delivery and returns the parsed event. Verification happens BEFORE parsing, and the only way to obtain a WebhookEvent is through this function, so an unverified payload cannot reach your business logic by accident.
payload must be the RAW request body, exactly the bytes that arrived. Reading the body into a struct and re-encoding it will change them and the signature will not match. In net/http that means io.ReadAll(r.Body) before any json.Decode.
signatureHeader is the WebhookSignatureHeader value: "t={unix_seconds},v1={hex}". secret is the endpoint's whsec_ secret, shown once when the endpoint was created.
Every failure returns a *WebhookVerificationError carrying a WebhookReason* on .Reason. Nothing panics and no other error type comes out, so a malformed or hostile header is an ordinary rejection path:
body, err := io.ReadAll(r.Body)
if err != nil {
w.WriteHeader(http.StatusBadRequest)
return
}
event, err := dominaite.VerifyWebhook(body, r.Header.Get(dominaite.WebhookSignatureHeader), secret)
if err != nil {
w.WriteHeader(http.StatusBadRequest)
return
}
if !alreadySeen(event.ID) { // delivery is at-least-once: dedupe on ID
enqueue(event) // do the work off the request path
}
w.WriteHeader(http.StatusOK) // answer fast; a slow 2xx counts as a failure
Example ¶
The doc example must stay compilable and correct.
event, err := VerifyWebhook(
[]byte(webhookVector.Body),
webhookVector.Header,
webhookVector.Secret,
atVectorTime(),
)
if err != nil {
fmt.Println("rejected:", err)
return
}
fmt.Println(event.Type, event.Data.Amount, event.Data.Currency)
Output: payment.succeeded 8440 EUR
type WebhookVerificationError ¶ added in v0.2.0
type WebhookVerificationError struct {
// Reason is one of the WebhookReason* constants.
Reason string
// contains filtered or unexported fields
}
WebhookVerificationError means VerifyWebhook rejected a delivery. Nothing was parsed and nothing should be acted on.
Answer the HTTP request with 400 and no detail. Never echo the reason back to the caller: whoever sent an unverified request does not get to learn whether their secret or their timestamp was the problem.
event, err := dominaite.VerifyWebhook(body, r.Header.Get("X-Webhook-Signature"), secret)
var verr *dominaite.WebhookVerificationError
if errors.As(err, &verr) {
log.Printf("rejected webhook: %s", verr.Reason) // your logs only
w.WriteHeader(http.StatusBadRequest)
return
}
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. |
|
webhook-handler
command
Command webhook-handler is a runnable webhook receiver.
|
Command webhook-handler is a runnable webhook receiver. |